Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C
12.7 KB
Raw Blame
"""image_engine.py on its own: PNG, request rules, the protocol client, saving.

The PNG codec is checked against zlib-level ground truth (a hand-built file
with every filter type) as well as round trips, because a codec that only
ever decodes its own output can agree with itself about a wrong format.
"""
import json
import os
import struct
import sys
import tempfile
import threading
import time
import unittest
import zlib
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from qwen_image_fixture import STUB, make_fake_pipeline, stub_env  # noqa: E402

import image_engine as ie  # noqa: E402

INFO = dict(ie.DEFAULT_INFO)


def _chunk(kind, data):
    body = kind + data
    return struct.pack(">I", len(data)) + body + struct.pack(">I", zlib.crc32(body) & 0xffffffff)


def _png_with_filters(width, height, channels, pixels, filters):
    """A PNG whose rows use the given filter types, encoded straight from the
    PNG specification (independently of image_engine's encoder)."""
    stride = width * channels
    raw = bytearray()
    previous = bytes(stride)
    for y in range(height):
        row = pixels[y * stride:(y + 1) * stride]
        kind = filters[y % len(filters)]
        out = bytearray(stride)
        for i in range(stride):
            a = row[i - channels] if i >= channels else 0
            b = previous[i]
            c = previous[i - channels] if i >= channels else 0
            if kind == 0:
                pred = 0
            elif kind == 1:
                pred = a
            elif kind == 2:
                pred = b
            elif kind == 3:
                pred = (a + b) >> 1
            else:
                p = a + b - c
                pa, pb, pc = abs(p - a), abs(p - b), abs(p - c)
                pred = a if pa <= pb and pa <= pc else (b if pb <= pc else c)
            out[i] = (row[i] - pred) & 255
        raw.append(kind)
        raw += out
        previous = row
    colour = {1: 0, 2: 4, 3: 2, 4: 6}[channels]
    return (b"\x89PNG\r\n\x1a\n" +
            _chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, colour, 0, 0, 0)) +
            _chunk(b"IDAT", zlib.compress(bytes(raw))) + _chunk(b"IEND", b""))


def _noise(count, seed=1):
    state = seed
    out = bytearray(count)
    for i in range(count):
        state = (state * 1103515245 + 12345) & 0x7fffffff
        out[i] = state >> 16 & 255
    return bytes(out)


class PngTest(unittest.TestCase):
    def test_round_trip_every_channel_count(self):
        for channels in (1, 2, 3, 4):
            with self.subTest(channels=channels):
                width, height = 37, 23
                pixels = _noise(width * height * channels, channels)
                png = ie.encode_png(width, height, pixels, channels)
                self.assertTrue(png.startswith(b"\x89PNG\r\n\x1a\n"))
                self.assertEqual(ie.decode_png(png), (width, height, channels, pixels))

    def test_decodes_every_filter_type(self):
        width, height, channels = 19, 10, 4
        pixels = _noise(width * height * channels, 7)
        png = _png_with_filters(width, height, channels, pixels, [0, 1, 2, 3, 4])
        self.assertEqual(ie.decode_png(png)[3], pixels)

    def test_encoder_output_is_a_valid_png_by_the_spec(self):
        """Decode our PNG without our decoder: chunk CRCs, IHDR, and each row's
        Up filter undone by hand."""
        width, height = 5, 4
        pixels = _noise(width * height * 4, 3)
        png = ie.encode_png(width, height, pixels, 4)
        pos, idat, ihdr = 8, b"", None
        while pos < len(png):
            length, kind = struct.unpack(">I4s", png[pos:pos + 8])
            body = png[pos + 8:pos + 8 + length]
            crc = struct.unpack(">I", png[pos + 8 + length:pos + 12 + length])[0]
            self.assertEqual(zlib.crc32(kind + body) & 0xffffffff, crc, kind)
            if kind == b"IHDR":
                ihdr = struct.unpack(">IIBBBBB", body)
            elif kind == b"IDAT":
                idat += body
            pos += 12 + length
        self.assertEqual(ihdr, (width, height, 8, 6, 0, 0, 0))
        raw = zlib.decompress(idat)
        stride = width * 4
        previous = bytes(stride)
        for y in range(height):
            kind = raw[y * (stride + 1)]
            row = raw[y * (stride + 1) + 1:(y + 1) * (stride + 1)]
            self.assertIn(kind, (0, 2))
            if kind == 2:
                row = bytes((v + p) & 255 for v, p in zip(row, previous))
            self.assertEqual(row, pixels[y * stride:(y + 1) * stride])
            previous = row

    def test_corruption_and_unsupported_formats_are_refused(self):
        png = bytearray(ie.encode_png(4, 4, bytes(64), 4))
        png[-20] ^= 0xff
        with self.assertRaises(ValueError):
            ie.decode_png(bytes(png))
        with self.assertRaises(ValueError):
            ie.decode_png(b"GIF89a")
        sixteen = (b"\x89PNG\r\n\x1a\n" +
                   _chunk(b"IHDR", struct.pack(">IIBBBBB", 1, 1, 16, 2, 0, 0, 0)) +
                   _chunk(b"IDAT", zlib.compress(bytes(7))) + _chunk(b"IEND", b""))
        with self.assertRaisesRegex(ValueError, "8-bit"):
            ie.decode_png(sixteen)
        with self.assertRaises(ValueError):
            ie.encode_png(4, 4, bytes(10), 4)


class RequestRulesTest(unittest.TestCase):
    def test_defaults_come_from_ready(self):
        request = ie.image_request({"prompt": "a cat", "seed": 3}, INFO)
        self.assertEqual((request["width"], request["height"], request["steps"],
                          request["seed"]), (768, 512, 8, 3))
        info = dict(INFO, default_width=1024, default_height=576, default_steps=4)
        request = ie.image_request({"prompt": "a cat"}, info)
        self.assertEqual((request["width"], request["height"], request["steps"]), (1024, 576, 4))
        self.assertFalse(request["seed_given"])
        self.assertTrue(0 <= request["seed"] <= ie.MAX_SEED)

    def test_the_contract_sizes(self):
        for size in ("768x512", "1024x576", "256x2048", "2048x2048", "512X288", " 512 x 512 "):
            with self.subTest(size=size):
                ie.image_request({"prompt": "x", "size": size}, INFO)
        for size in ("768x432", "250x256", "224x256", "2080x256", "768", "x", "0x0"):
            with self.subTest(size=size):
                with self.assertRaises(ie.ImageRequestError) as caught:
                    ie.image_request({"prompt": "x", "size": size}, INFO)
                self.assertEqual(caught.exception.param, "size")
        self.assertEqual(ie.nearest_size(768, 432, INFO), (768, 448))
        for preset in ie.SIZE_PRESETS:
            self.assertIsNone(ie.check_size(*preset, INFO), preset)

    def test_each_parameter_names_itself(self):
        cases = (({"prompt": ""}, "prompt"), ({"prompt": "x", "n": 2}, "n"),
                 ({"prompt": "x", "steps": 0}, "steps"), ({"prompt": "x", "seed": -5}, "seed"),
                 ({"prompt": "x", "seed": 2**40}, "seed"),
                 ({"prompt": "x", "width": 300}, "width"),
                 ({"prompt": "x", "height": 100}, "height"),
                 ({"prompt": "x", "response_format": "url"}, "response_format"),
                 ({"prompt": "x", "size": "512x512", "height": 512}, "size"))
        for body, param in cases:
            with self.subTest(body=body):
                with self.assertRaises(ie.ImageRequestError) as caught:
                    ie.image_request(body, INFO)
                self.assertEqual(caught.exception.param, param)


class ImageEngineTest(unittest.TestCase):
    def setUp(self):
        self.tmp = tempfile.TemporaryDirectory()
        self.addCleanup(self.tmp.cleanup)
        self.model = make_fake_pipeline(Path(self.tmp.name) / "m")
        self.logs = []

    def engine(self, delay=0.0, **extra):
        engine = ie.ImageEngine(STUB, self.model, env=stub_env(delay, **extra),
                                on_log=self.logs.append, on_stderr=self.logs.append)
        self.addCleanup(engine.close, 5)
        return engine

    def test_ready_carries_the_contract_fields(self):
        info = self.engine().info
        for key, value in (("default_width", 768), ("default_height", 512), ("multiple", 32),
                           ("min_side", 256), ("max_side", 2048), ("default_steps", 8)):
            self.assertEqual(info[key], value)

    def test_generate_reports_progress_previews_and_the_image(self):
        engine = self.engine()
        progress, previews = [], []
        result = engine.generate("a cat", 256, 288, 3, 9, preview=True,
                                 on_progress=progress.append,
                                 on_preview=lambda meta, px: previews.append((meta, len(px))))
        self.assertEqual((result["width"], result["height"], result["seed"], result["steps"]),
                         (256, 288, 9, 3))
        self.assertEqual(len(result["rgba"]), 256 * 288 * 4)
        self.assertEqual([p["stage"] for p in progress][0], "encode")
        self.assertEqual(progress[-1]["stage"], "decode")
        self.assertEqual(len(previews), 3)
        meta, size = previews[0]
        self.assertEqual(size, meta["width"] * meta["height"] * 3)
        # stderr was drained from the first byte, into our callable
        self.assertTrue(any("stub" in line for line in self.logs))

    def test_engine_error_leaves_the_engine_usable(self):
        engine = self.engine()
        with self.assertRaisesRegex(ie.ImageEngineError, "stub failure"):
            engine.generate("__stub_error__", 256, 256, 2, 1)
        with self.assertRaisesRegex(ie.ImageEngineError, "multiple of 32"):
            engine.generate("x", 250, 256, 2, 1)      # the engine's own validation
        self.assertTrue(engine.alive)
        self.assertEqual(engine.generate("x", 256, 256, 2, 1)["width"], 256)

    def test_cancel_between_steps(self):
        engine = self.engine(delay=0.2)
        seen = []
        started = time.time()
        with self.assertRaises(ie.ImageCancelled):
            engine.generate("x", 256, 256, 30, 1, on_progress=seen.append,
                            cancelled=lambda: len(seen) >= 2)
        self.assertLess(time.time() - started, 4)       # 30 steps would take 6 s
        self.assertTrue(engine.alive)
        self.assertEqual(engine.generate("y", 256, 256, 2, 2)["seed"], 2)

    def test_a_crash_is_reported_and_the_engine_marked_dead(self):
        engine = self.engine()
        with self.assertRaisesRegex(ie.ImageEngineError, "exited"):
            engine.generate("__stub_crash__", 256, 256, 4, 1)
        self.assertFalse(engine.alive)
        with self.assertRaises(ie.ImageEngineError):
            engine.generate("x", 256, 256, 2, 1)

    def test_stray_output_is_ignored(self):
        engine = self.engine()
        result = engine.generate("__stub_garbage__", 256, 256, 2, 1)
        self.assertEqual(result["width"], 256)
        self.assertTrue(any("stray" in line for line in self.logs))

    def test_an_engine_that_dies_while_loading(self):
        with self.assertRaisesRegex(ie.ImageEngineError, "exited while loading"):
            ie.ImageEngine(STUB, str(Path(self.tmp.name) / "missing"), env=stub_env(),
                           on_stderr=lambda _l: None)

    def test_a_load_timeout(self):
        with self.assertRaisesRegex(ie.ImageEngineError, "did not become ready"):
            ie.ImageEngine(STUB, self.model, env=stub_env(QWENIMAGE_STUB_LOAD_DELAY=5),
                           load_timeout=0.5, on_stderr=lambda _l: None)

    def test_engine_command_runs_a_python_stub_under_this_interpreter(self):
        self.assertEqual(ie.engine_command("x/qwenimage", "m"), ["x/qwenimage", "--model", "m",
                                                                  "--serve"])
        self.assertEqual(ie.engine_command("t/stub.py", "m")[:2], [sys.executable, "t/stub.py"])


class SavingTest(unittest.TestCase):
    def test_names_describe_and_never_overwrite(self):
        with tempfile.TemporaryDirectory() as tmp:
            png = ie.encode_png(1, 1, b"\0\0\0\0", 4)
            first = ie.save_png(png, "A red fox, in the snow!", 42, tmp, now=0)
            second = ie.save_png(png, "A red fox, in the snow!", 42, tmp, now=0)
            self.assertNotEqual(first, second)
            self.assertTrue(os.path.basename(first).endswith("-a-red-fox-in-the-snow-s42.png"))
            self.assertTrue(second.endswith("-s42-2.png"))
            unicode_name = ie.save_png(png, "日本の猫", 1, tmp, now=0)
            self.assertIn("-image-s1", unicode_name)
            self.assertEqual(sorted(os.listdir(tmp)), sorted(
                os.path.basename(p) for p in (first, second, unicode_name)))

    def test_default_directory_and_override(self):
        self.assertTrue(ie.image_dir({}).endswith("colibri-images"))
        self.assertEqual(ie.image_dir({"COLI_IMAGE_DIR": "/x/y"}), "/x/y")


if __name__ == "__main__":
    unittest.main()