Skip to content

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

11.1 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Run a bounded inspect -> score -> correction-hint loop."""

from __future__ import annotations

import argparse
import json
import os
import shlex
import shutil
import subprocess
from collections.abc import Callable
from pathlib import Path
from typing import Any

from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.qa import inspect as inspect_mod
from sprite_gen.qa import score as score_mod
from sprite_gen.spec.runio import LOCK_FILENAME, REQUEST_FILENAME, atomic_write_text, refuse_overlap, relative_posix, same_folder
from sprite_gen.util.console import utf8_streams

BEST_CANDIDATE = "best-candidate"
REPORT = "correction-loop.report.json"


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--run-dir", required=True, type=Path)
    parser.add_argument("--states", default="all")
    parser.add_argument("--out-dir", type=Path)
    parser.add_argument("--max-passes", type=int, default=3)
    parser.add_argument("--min-attempts", type=int, default=1)
    parser.add_argument("--pass-score", type=float, default=90.0)
    parser.add_argument("--provider-command", help="optional command template; {prompt_file}, {next_run_dir}, {attempt}")
    parser.add_argument("--dry-run", action="store_true")
    parser.add_argument("--no-preserve-best", action="store_true")
    return parser


def _skipped_by_copy(out_dir: Path) -> Callable[[Path], bool]:
    """What the best candidate's copy of a run dir leaves out: its lock, `__pycache__`, and the loop's out dir where
    it lies in the run dir, as the default one does (the copy would copy itself into itself). A link to the out dir
    is not left out: it is an input that reaches the loop's own output, refused before the loop starts."""
    return lambda path: (path.name in (LOCK_FILENAME, "__pycache__")
                         or (not path.is_symlink() and same_folder(path, out_dir)))


def _copied(source: Path, skipped: Callable[[Path], bool]) -> list[Path]:
    """Every entry the copy of `source` reads, as found there: each file, folder and link (`shutil.copytree` reads a
    linked file's bytes and a linked folder's content), the linked folders walked too."""
    found: list[Path] = []
    todo, walked = [source], set()
    while todo:
        with os.scandir(todo.pop()) as entries:
            for entry in entries:
                path = Path(entry.path)
                if skipped(path):
                    continue
                found.append(path)
                if entry.is_dir():
                    folder = entry.stat()
                    if (folder.st_dev, folder.st_ino) not in walked:  # a folder linked twice, or a link loop, once
                        walked.add((folder.st_dev, folder.st_ino))
                        todo.append(path)
    return sorted(found)


def _attempt(out_dir: Path, attempt: int) -> dict[str, Path]:
    """What attempt `attempt` writes in the out dir: its folder and, in it, the inspection, the score, the hints and the
    provider's log (written when a provider runs after the attempt)."""
    folder = out_dir / f"attempt-{attempt}"
    return {"folder": folder, "inspect": folder / "inspect.json", "score": folder / "score.json",
            "hints": folder / "correction-hints.txt", "log": folder / "provider.log"}


def _candidate(out_dir: Path, attempt: int) -> Path:
    """Where the provider makes the run dir attempt `attempt` inspects."""
    return out_dir / f"candidate-{attempt}"


def _written(out_dir: Path, *, passes: int, preserve_best: bool) -> list[Path]:
    """Every entry the loop writes in the out dir, at the path it writes: each attempt's folder and its files, each
    candidate the provider makes (a loop of more than one pass runs a provider), the best candidate's copy and the
    report."""
    written: list[Path] = []
    for attempt in range(1, passes + 1):
        files = _attempt(out_dir, attempt)
        written += [path for key, path in files.items() if key != "log" or attempt < passes]
        if attempt > 1:
            written.append(_candidate(out_dir, attempt))
    return [*written, *([out_dir / BEST_CANDIDATE] if preserve_best else []), out_dir / REPORT]


def _take_away(path: Path) -> None:
    """Remove what an earlier loop left at `path`, one of the loop's own outputs, never following a link: a link or a
    file is unlinked, a folder removed with what it holds (`shutil.rmtree` unlinks the links in it)."""
    if path.is_symlink() or path.is_file():
        path.unlink()
    elif path.exists():
        shutil.rmtree(path)


def _copy_run_dir(source: Path, target: Path, skipped: Callable[[Path], bool]) -> None:
    _take_away(target)

    def ignore(folder: str, names: list[str]) -> set[str]:
        return {name for name in names if skipped(Path(folder) / name)}

    shutil.copytree(source, target, ignore=ignore)


def _write_hints(path: Path, hints: list[str]) -> None:
    body = "\n".join(f"- {hint}" for hint in hints) if hints else "- No correction hint; candidate passed."
    atomic_write_text(path, body + "\n")


def run_loop(
    run_dir: Path,
    *,
    states: str = "all",
    out_dir: Path | None = None,
    max_passes: int = 3,
    min_attempts: int = 1,
    pass_score: float = 90.0,
    provider_command: str | None = None,
    dry_run: bool = False,
    preserve_best: bool = True,
) -> dict[str, Any]:
    if max_passes < 1:
        raise SystemExit("--max-passes must be at least 1")
    if min_attempts < 1 or min_attempts > max_passes:
        raise SystemExit("--min-attempts must be between 1 and --max-passes")
    given = run_dir
    run_dir = run_dir.expanduser().resolve()
    out_dir = (out_dir or (run_dir / "correction-loop")).expanduser().resolve()
    # The loop never writes over, moves or deletes the run it reads: the run dir, and every entry its best candidate's
    # copy reads there (each with every link or folder its path looks up), is never anything the loop writes — the out
    # dir and each entry the loop writes in it, at the path it writes, a link already there followed — nor inside one.
    # The out dir may lie in the run dir (the default does): it is added to it, and the copy leaves it out.
    skipped = _skipped_by_copy(out_dir)
    found = _copied(run_dir, skipped) if run_dir.is_dir() else []
    written = _written(out_dir, passes=max_passes if provider_command and not dry_run else 1, preserve_best=preserve_best)
    refuse_overlap({"--run-dir": given, **{f"{relative_posix(p, run_dir)} in --run-dir": p for p in found}},
                   {"--out-dir": out_dir, **{f"{relative_posix(p, out_dir)} in --out-dir": p for p in written}},
                   replaces="the loop writes its attempts and best candidate there")
    out_dir.mkdir(parents=True, exist_ok=True)
    attempts: list[dict[str, Any]] = []
    best: dict[str, Any] | None = None
    current = run_dir

    for attempt in range(1, max_passes + 1):
        files = _attempt(out_dir, attempt)
        files["folder"].mkdir(parents=True, exist_ok=True)
        inspect_report = inspect_mod.inspect_run(current, states=states)
        scored = score_mod.score_inspection(inspect_report)
        atomic_write_text(files["inspect"], json.dumps(inspect_report, ensure_ascii=False, indent=2) + "\n")
        atomic_write_text(files["score"], json.dumps(scored, ensure_ascii=False, indent=2) + "\n")
        _write_hints(files["hints"], scored["hints"])
        record = {
            "attempt": attempt,
            "run_dir": str(current),
            "inspect_report": str(files["inspect"]),
            "score_report": str(files["score"]),
            "hint_file": str(files["hints"]),
            "ok": scored["ok"],
            "overall_score": scored["overall_score"],
            "candidate_rank": scored["candidate_rank"],
        }
        attempts.append(record)
        if best is None or (scored["candidate_rank"], scored["overall_score"]) > (
            best["candidate_rank"],
            best["overall_score"],
        ):
            best = record
        if attempt >= min_attempts and scored["ok"] and float(scored["overall_score"]) >= pass_score:
            break
        if attempt == max_passes:
            break
        if dry_run:
            break
        if not provider_command:
            raise SystemExit("correction loop needs --provider-command, or use --dry-run for an inspect/score/hint demo")
        next_run_dir = _candidate(out_dir, attempt + 1)
        # The provider makes the run dir there: an earlier loop's candidate is taken away first, so nothing it held (a
        # link into the run among it) is written through.
        _take_away(next_run_dir)
        prompt_file = files["hints"]
        # The template is split first and each argument filled in after, so a substituted
        # path is never re-read as shell syntax: POSIX splitting would drop the backslashes
        # of a Windows path and break a path that holds a space or a quote.
        argv = [arg.format(prompt_file=str(prompt_file), next_run_dir=str(next_run_dir), attempt=attempt + 1)
                for arg in shlex.split(provider_command)]
        command = shlex.join(argv)
        completed = subprocess.run(argv, capture_output=True, text=True)
        atomic_write_text(
            files["log"],
            completed.stdout + ("\n--- stderr ---\n" + completed.stderr if completed.stderr else ""),
        )
        if completed.returncode != 0:
            raise SystemExit(f"provider command failed with exit {completed.returncode}: {command}")
        if not (next_run_dir / REQUEST_FILENAME).is_file():
            raise SystemExit(f"provider command did not create a sprite-gen run dir: {next_run_dir}")
        current = next_run_dir

    assert best is not None
    preserved_best = None
    if preserve_best:
        preserved = out_dir / BEST_CANDIDATE
        _copy_run_dir(Path(best["run_dir"]), preserved, skipped)
        preserved_best = str(preserved)
    result = {
        "ok": bool(attempts and attempts[-1]["ok"] and float(attempts[-1]["overall_score"]) >= pass_score),
        "kind": "sprite-gen-correction-loop-report",
        "dry_run": dry_run,
        "min_attempts": min_attempts,
        "max_passes": max_passes,
        "attempts": attempts,
        "best_candidate": best,
        "preserved_best": preserved_best,
    }
    atomic_write_text(out_dir / REPORT, json.dumps(result, ensure_ascii=False, indent=2) + "\n")
    return result


def _run(args: argparse.Namespace) -> int:
    result = run_loop(
        args.run_dir,
        states=args.states,
        out_dir=args.out_dir,
        max_passes=args.max_passes,
        min_attempts=args.min_attempts,
        pass_score=args.pass_score,
        provider_command=args.provider_command,
        dry_run=args.dry_run,
        preserve_best=not args.no_preserve_best,
    )
    print(json.dumps({k: v for k, v in result.items() if k != "attempts"}, ensure_ascii=False, indent=2))
    return 0 if result["ok"] else 1


def run(**kwargs: object) -> int:
    args = namespace_from_kwargs(_build_parser(), kwargs)
    return _run(args)


def main() -> int:
    utf8_streams()
    return _run(_build_parser().parse_args())


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