Skip to content

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

16.0 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Facing regression contracts; all generation and vision calls are offline."""
import argparse
import json
import shutil
from pathlib import Path
from types import SimpleNamespace

import pytest
from PIL import Image, ImageOps

from sprite_gen import gen
from sprite_gen.gen import codex_provider, facing, facing_vision, openai_provider, grok_provider, xai
from sprite_gen.gen.base import ProviderRun

FIXTURES = Path(__file__).parents[1] / "fixtures" / "facing"


class Backend:
    name = "openai"
    transparency = "native"

    def __init__(self, direction="left", failure=None, regenerated_direction="right", image_direction=None):
        self.image_direction = image_direction or direction
        self.regenerated_direction = regenerated_direction
        self.direction, self.failure = direction, failure
        self.generations, self.inspections = [], []

    def generate(self, request, workdir):
        self.generations.append(request)
        source = self.regenerated_direction if len(self.generations) > 1 else self.image_direction
        if source == "unknown":
            source = "front"
        shutil.copyfile(FIXTURES / f"{source}.png", request.raw)
        return ProviderRun(self.name, 2, model="test-image", extra={"usage": {"output_tokens": 10}})

    def inspect_facing(self, path, workdir):
        self.inspections.append(path)
        if self.failure:
            raise self.failure
        direction = self.regenerated_direction if len(self.generations) > 1 else self.direction
        return json.dumps({"direction": direction, "confidence": 0.95}), {"model": "test-vision", "usage": {"input_tokens": 4}}


def generate(tmp_path, monkeypatch, backend, **kwargs):
    monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: backend)
    return gen.generate_image("openai", "a toy robot", tmp_path / "out.png",
                              refs=[FIXTURES / "left.png"], **{"facing": "right", **kwargs})


def test_video_loop_takes_the_facings_declared_here():
    from sprite_gen.video import loop

    parser = argparse.ArgumentParser()
    loop.add_arguments(parser)
    assert next(a for a in parser._actions if "--facing" in a.option_strings).choices is facing.FACINGS


@pytest.mark.parametrize("direction", ["left", "right", "front"])
def test_three_fixture_directions_only_opposite_is_mirrored(tmp_path, monkeypatch, direction):
    backend = Backend(direction)
    result = generate(tmp_path, monkeypatch, backend, facing_fix="mirror")
    original = Image.open(FIXTURES / f"{direction}.png")
    expected = ImageOps.mirror(original) if direction == "left" else original
    assert Image.open(result.out).tobytes() == expected.tobytes()
    assert Image.open(result.raw).tobytes() == original.tobytes()
    assert len(backend.inspections) == len(backend.generations) == 1
    assert "facing right" in backend.generations[0].prompt
    report = result.to_dict()["extra"]["facing"]
    assert report["direction"] == direction and report["confidence"] == 0.95
    assert report["action"] == ("mirror" if direction == "left" else "none")


def test_left_request_mirrors_right_and_preserves_alpha_and_preview(tmp_path, monkeypatch):
    result = generate(tmp_path, monkeypatch, Backend("right"), facing="left", facing_fix="mirror",
                      transparent=True, alpha_mode="native", white_check=tmp_path / "white.png")
    original = Image.open(FIXTURES / "right.png")
    assert Image.open(result.out).tobytes() == ImageOps.mirror(original).tobytes()
    expected = Image.new("RGBA", original.size, "white")
    expected.alpha_composite(ImageOps.mirror(original))
    assert Image.open(tmp_path / "white.png").convert("RGBA").tobytes() == expected.tobytes()
    assert result.extra["facing"]["final_direction"] == "left"


def test_default_and_none_preserve_bytes_despite_wrong_observation(tmp_path, monkeypatch):
    # the default is `none`, so an explicit `facing_fix="none"` runs the same code
    backend = Backend("left", image_direction="right")
    result = generate(tmp_path, monkeypatch, backend)
    assert result.out.read_bytes() == result.raw.read_bytes() == (FIXTURES / "right.png").read_bytes()
    report = result.extra["facing"]
    assert report["fix"] == "none" and report["action"] == "none"
    assert report["reason"] == "correction-disabled"
    assert report["direction"] == report["final_direction"] == "left"
    assert report["final_direction_source"] == "observation"
    assert report["requested"] == "right" and report["model"] == "test-vision"
    assert len(backend.generations) == len(backend.inspections) == 1
    assert "facing right" in result.prompt


@pytest.mark.parametrize("failure", [RuntimeError("private"), SystemExit("private")])
def test_failed_vision_is_unknown_and_preserves_file(tmp_path, monkeypatch, failure, capsys):
    result = generate(tmp_path, monkeypatch, Backend(failure=failure))
    report = result.extra["facing"]
    assert report["direction"] == "unknown" and report["confidence"] is None
    assert report["action"] == "none" and "vision-call-failed" in report["reason"]
    assert "private" not in json.dumps(report)
    assert "facing unknown" in capsys.readouterr().err
    assert result.out.read_bytes() == (FIXTURES / "left.png").read_bytes()


@pytest.mark.parametrize("rechecked", ["right", "left", "front", "unknown"])
def test_regen_rechecks_once_and_mirrors_only_a_known_opposite(tmp_path, monkeypatch, rechecked):
    backend = Backend(regenerated_direction=rechecked)
    result = generate(tmp_path, monkeypatch, backend, facing_fix="regen")
    report = result.extra["facing"]
    assert len(backend.generations) == len(backend.inspections) == 2
    assert "CORRECTION REQUIRED" in backend.generations[1].prompt
    assert "facing right" in backend.generations[1].prompt
    expected = "right" if rechecked in ("left", "right") else "front"
    assert Image.open(result.out).tobytes() == Image.open(FIXTURES / f"{expected}.png").tobytes()
    assert result.elapsed_seconds == 4
    assert result.extra["usage"] == report["regeneration"]["extra"]["usage"] == {"output_tokens": 10}
    assert report["action"] == "regen"
    assert report["regeneration"]["recheck"]["direction"] == rechecked
    assert report["regeneration"]["recheck"]["usage"] == {"input_tokens": 4}
    assert report.get("fallback") == ("mirror" if rechecked == "left" else None)
    assert report["final_direction"] == ("right" if rechecked in ("left", "right") else rechecked)
    assert report["final_direction_source"] == ("mirror-of-recheck" if rechecked == "left" else "regeneration-recheck")
    if rechecked in ("unknown", "front"):
        assert report["reason"].startswith("regeneration-facing-unresolved:")


def test_regen_failure_is_terminal_and_never_reuses_stale_output(tmp_path, monkeypatch):
    backend = Backend()
    original_generate = backend.generate
    def fail_second(request, workdir):
        if backend.generations:
            raise SystemExit("regeneration failed")
        return original_generate(request, workdir)
    backend.generate = fail_second
    out = tmp_path / "out.png"
    out.write_bytes(b"existing-output")
    with pytest.raises(SystemExit, match="regeneration failed"):
        generate(tmp_path, monkeypatch, backend, facing_fix="regen")
    assert out.read_bytes() == b"existing-output"


def test_no_ref_does_not_inspect_or_change_prompt(tmp_path, monkeypatch):
    backend = Backend()
    monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: backend)
    result = gen.generate_image("openai", "a toy robot", tmp_path / "out.png")
    assert not backend.inspections and "facing" not in result.extra
    assert backend.generations[0].prompt == "a toy robot"


@pytest.mark.parametrize("text", ['{}', 'null', '[]', 'left or right', '{"direction":"left","confidence":true}',
                                 '{"direction":"left","confidence":2}', '{"direction":"right","confidence":NaN}',
                                 '{"direction":"back","confidence":0.9}'])
def test_malformed_observation_is_unknown(text):
    assert facing.parse_observation(text)["reason"] == "invalid-vision-response"


def test_one_word_never_invents_confidence():
    assert facing.parse_observation(" LEFT ") == {"direction": "left", "confidence": None,
                                                "confidence_source": "not-reported"}


@pytest.mark.parametrize("text,direction,confidence", [
    (' {"direction":"left","confidence":0.9} ', "left", 0.9),
    (' \n```json\n{"direction":"right","confidence":1}\n```\n ', "right", 1),
    ('```\n{"direction":"front","confidence":0.8}\n```', "front", 0.8),
    ('left', "left", None),
    ('The character faces RIGHT.', "right", None),
    ('unreadable garbage', "unknown", None),
])
def test_provider_response_formats(text, direction, confidence):
    observed = facing.parse_observation(text)
    assert observed["direction"] == direction
    assert observed["confidence"] == confidence
    if direction == "unknown":
        assert observed["reason"] == "invalid-vision-response"


def vision_response():
    return {"model": "test-vision", "status": "completed", "usage": {"input_tokens": 4},
            "output": [{"type": "message", "content": [{"type": "output_text", "text": '```json\n{"direction":"left","confidence":0.9}\n```'}]}]}


@pytest.mark.parametrize("provider", ["openai", "grok"])
def test_rest_vision_uses_same_provider_credential_once(monkeypatch, tmp_path, provider):
    seen = []
    if provider == "openai":
        monkeypatch.setattr(openai_provider, "resolve_credential", lambda: "synthetic")
        def http(url, token, data, content_type, **kw):
            seen.append((url, token, json.loads(data)))
            return 200, vision_response(), {}
        monkeypatch.setattr(openai_provider, "http_image", http)
        backend = openai_provider.OpenAIProvider()
    else:
        monkeypatch.setattr(xai, "resolve_credential", lambda: xai.Credential("synthetic", "grok-login"))
        def http(method, url, token, body, **kw):
            seen.append((url, token, body))
            return 200, vision_response()
        monkeypatch.setattr(xai, "http_json", http)
        backend = grok_provider.GrokProvider()
    report = facing.inspect(backend, FIXTURES / "left.png", tmp_path)
    assert len(seen) == 1 and seen[0][1] == "synthetic"
    assert seen[0][0] == ("https://api.openai.com/v1/responses" if provider == "openai" else "https://api.x.ai/v1/responses")
    body = seen[0][2]
    assert body["store"] is False
    assert body["input"][0]["content"][1]["image_url"].startswith("data:image/png;base64,")
    assert report["direction"] == "left" and report["usage"] == {"input_tokens": 4}
    assert report["auth_source"] == ("OPENAI_API_KEY" if provider == "openai" else "grok-login")


def test_rest_rejection_is_unknown_without_retry(monkeypatch, tmp_path):
    calls = []
    monkeypatch.setattr(openai_provider, "resolve_credential", lambda: "synthetic")
    def http(*a, **kw):
        calls.append(1)
        return 403, {"error": "sensitive"}, {}
    monkeypatch.setattr(openai_provider, "http_image", http)
    report = facing.inspect(openai_provider.OpenAIProvider(), FIXTURES / "left.png", tmp_path)
    assert len(calls) == 1 and report["direction"] == "unknown"
    assert "sensitive" not in json.dumps(report)


def test_codex_vision_reads_new_answer_and_scrubs_identity(monkeypatch, tmp_path):
    seen = []
    monkeypatch.setenv("ORCHESTRATOR_MEMBER_ID", "synthetic")
    def run(command, **kwargs):
        seen.append((command, kwargs))
        Path(command[command.index("-o") + 1]).write_text('right')
        return SimpleNamespace(returncode=0)
    monkeypatch.setattr(facing_vision.subprocess, "run", run)
    monkeypatch.setattr(codex_provider, "codex_login", lambda: codex_provider.CodexLogin(codex_provider.AUTH_SOURCE_LOGIN))
    text, metadata = facing_vision.codex_inspect(FIXTURES / "left.png", tmp_path)
    assert text == "right" and metadata["auth_source"] == "codex-login"
    assert len(seen) == 1 and "--ephemeral" in seen[0][0] and "read-only" in seen[0][0]
    assert "ORCHESTRATOR_MEMBER_ID" not in seen[0][1]["env"]
    assert not list(tmp_path.iterdir())


def test_cli_options_reach_report(tmp_path, monkeypatch):
    # `--facing-fix` defaults to `none`, so passing it runs the same code
    backend = Backend("right")
    monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: backend)
    report = tmp_path / "report.json"
    assert gen.main(["--provider", "openai", "--prompt", "robot", "--ref", str(FIXTURES / "right.png"),
                     "--out", str(tmp_path / "out.png"), "--report", str(report),
                     "--facing", "left"]) == 0
    facing_report = json.loads(report.read_text())["extra"]["facing"]
    assert facing_report["requested"] == "left" and facing_report["action"] == "none"
    assert facing_report["fix"] == "none"
    assert (tmp_path / "out.png").read_bytes() == (FIXTURES / "right.png").read_bytes()


def test_regeneration_recheck_failure_preserves_regenerated_image(tmp_path, monkeypatch):
    backend = Backend()
    inspect = backend.inspect_facing
    def fail_second(path, workdir):
        if backend.inspections:
            backend.inspections.append(path)
            raise TimeoutError("synthetic")
        return inspect(path, workdir)
    backend.inspect_facing = fail_second
    result = generate(tmp_path, monkeypatch, backend, facing_fix="regen")
    report = result.extra["facing"]
    assert len(backend.generations) == len(backend.inspections) == 2
    assert report["final_direction"] == "unknown" and "TimeoutError" in report["reason"]
    assert "fallback" not in report
    assert result.out.read_bytes() == (FIXTURES / "right.png").read_bytes()


def test_gen_cli_preserve_default_leaves_reference_prompt_unchanged(tmp_path, monkeypatch):
    backend = Backend()
    monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: backend)
    gen.main(["--provider", "openai", "--prompt", "front-facing robot", "--ref", str(FIXTURES / "front.png"),
              "--out", str(tmp_path / "out.png")])
    assert backend.generations[0].prompt == "front-facing robot" and not backend.inspections


def test_gen_set_reference_row_keeps_its_prompt(tmp_path, monkeypatch):
    from sprite_gen.gen import gen_set
    backend = Backend()
    monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: backend)
    prompt = tmp_path / "prompt.txt"
    prompt.write_text("a front-facing robot animation row")
    monkeypatch.setattr(gen_set, "run_logged", lambda command, log: gen.main(command[4:]))
    assert gen_set.run_gen_cli(prompt, tmp_path / "out.png", [FIXTURES / "front.png"],
                              tmp_path / "report.json", provider="openai", model=None,
                              log=tmp_path / "log.txt") == 0
    assert backend.generations[0].prompt == prompt.read_text() and not backend.inspections


def test_reroll_reference_row_keeps_its_prompt(tmp_path, monkeypatch):
    from sprite_gen.effects import reroll
    backend = Backend()
    monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: backend)
    monkeypatch.setattr(reroll, "load_request", lambda *a: {"fit": {"pixel_unfake": True}, "states": {"idle": {"frames": 2}}})
    monkeypatch.setattr(reroll, "identity_ref", lambda *a, **kw: FIXTURES / "front.png")
    monkeypatch.setattr(reroll, "prompt_rel", lambda *a: "prompt.txt")
    monkeypatch.setattr(reroll, "guide_rel", lambda *a: "guide.png")
    monkeypatch.setattr(reroll, "take_raw_rel", lambda *a: "out.png")
    monkeypatch.setattr(reroll, "record_take", lambda *a: None)
    (tmp_path / "prompt.txt").write_text("a back-facing robot animation row")
    reroll.reroll_state(tmp_path, "idle", provider="openai")
    assert backend.generations[0].prompt == "a back-facing robot animation row" and not backend.inspections


def test_interpolation_references_keep_their_prompt(monkeypatch):
    from sprite_gen.effects.interpolate import gen_interpolator
    backend = Backend()
    monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: backend)
    with Image.open(FIXTURES / "front.png") as im:
        gen_interpolator("codex")(im, im, 0.5, "front-facing robot, halfway pose")
    assert backend.generations[0].prompt == "front-facing robot, halfway pose" and not backend.inspections