mcpbytes-pixel-sprite 0.1.0__py3-none-any.whl

mcpbytes_pixel_sprite/__init__.py

@@ -0,0 +1 @@
+"""Fixed-layout pixel sprite generation and deterministic exports."""

mcpbytes_pixel_sprite/cli.py

@@ -0,0 +1,81 @@
+"""mcpbytes-pixel-sprite: 32x32 pixel-art character sprite sheets on your own GPU (or MCPBytes' with --cloud).
+
+  mcpbytes-pixel-sprite download                      fetch the pinned model files (~16 GB, once)
+  mcpbytes-pixel-sprite generate "a forest ranger"    write sheets, frames, walk GIFs, Godot/Unity exports
+  mcpbytes-pixel-sprite mcp                           serve the create_pixel_sprite tool over MCP (stdio)
+"""
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+from mcpbytes_core import hub
+from mcpbytes_core.errors import ToolError
+
+from .engine import OFFLOAD_MODES
+from .models import COMPONENTS
+
+
+def log(message):
+    print(message, file=sys.stderr, flush=True)
+
+
+def download():
+    if pending := hub.pending_bytes(COMPONENTS):
+        log(f"Downloading {pending / 1e9:.1f} GB of pinned model files from Hugging Face into its cache (resumable)")
+    hub.fetch(COMPONENTS)
+    log("Model files ready")
+
+
+def generate(args):
+    from .generate import run_cloud, run_local
+
+    options = {"description": args.description, "variants": args.variants, "transparent": not args.opaque,
+               "palette_colors": args.palette_colors, "frame_duration_ms": args.frame_duration_ms,
+               "palette": args.palette, "seed": args.seed}
+    out = args.out or Path("pixel-sprites") / time.strftime("%Y%m%d-%H%M%S")
+    if args.cloud:
+        return run_cloud(options, args.reference, out, idempotency_key=args.idempotency_key, progress=log)
+    if hub.missing(COMPONENTS):
+        download()
+    return run_local(options, args.reference, out, offload=args.offload, progress=log)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="mcpbytes-pixel-sprite", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("download", help="download the pinned model files (~16 GB) into the Hugging Face cache")
+    g = commands.add_parser("generate", help="generate 1-4 candidate sprite sheets from a description")
+    g.add_argument("description", help="one character, up to 4,000 characters")
+    g.add_argument("--reference", type=Path, help="PNG or JPEG of the character (yours to use)")
+    g.add_argument("--variants", type=int, default=1, help="candidate sheets, 1-4 (default 1)")
+    g.add_argument("--opaque", action="store_true", help="keep the background instead of removing it")
+    g.add_argument("--palette-colors", type=int, default=32, choices=(16, 32, 64))
+    g.add_argument("--palette", help="shared palette: 2-64 comma-separated #RRGGBB colors, no spaces")
+    g.add_argument("--frame-duration-ms", type=int, default=120, help="walk preview frame time, 40-1000 in steps of 10")
+    g.add_argument("--seed", type=int, help="0-4294967295; the same seed, inputs and hardware repeat a result")
+    g.add_argument("-o", "--out", type=Path, help="new or empty folder (default: pixel-sprites/<timestamp>)")
+    g.add_argument("--cloud", action="store_true", help="run on MCPBytes GPUs for credits (needs MCPBYTES_API_KEY)")
+    g.add_argument("--idempotency-key", help="with --cloud: the key printed by an interrupted run, to resume it without a new charge")
+    m = commands.add_parser("mcp", help="run the MCP server on stdio (for Claude, Cursor, VS Code and other MCP clients)")
+    m.add_argument("--cloud", action="store_true", help="serve the tool from MCPBytes GPUs for credits (needs MCPBYTES_API_KEY)")
+    for command in (g, m):
+        command.add_argument("--offload", choices=OFFLOAD_MODES, default="auto",
+                             help="GPU memory mode: none needs ~17 GB, model ~8 GB, sequential less (slowest); auto picks by GPU size")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "download":
+            download()
+        elif args.command == "generate":
+            print(json.dumps(generate(args), indent=2))
+        else:
+            from .server import serve
+
+            serve(cloud=args.cloud, offload=args.offload)
+    except ToolError as e:
+        log(f"mcpbytes-pixel-sprite: {e}")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)

mcpbytes_pixel_sprite/engine.py

@@ -0,0 +1,68 @@
+"""FLUX.2 [klein] base 4B with the pixel-spritesheet LoRA, loaded once from the pinned Hugging Face files."""
+
+import sys
+import threading
+
+from mcpbytes_core import hub
+from mcpbytes_core.gpu import require_cuda
+
+from .inference import request_options
+from .models import COMPONENTS, DOWNLOAD_COMMAND, ENCODER, LORA, TRANSFORMER
+
+# GPU memory modes, chosen by the card's total memory. Peaks and per-image times measured at 512x512 on an
+# RTX PRO 6000 with torch 2.8: "none" keeps every model resident (16.2 GiB reserved, 2.3 s); "model" moves
+# whole models on and off the GPU per stage (7.8 GiB, 7.4 s; the hosted 24 GiB cards run this way);
+# "sequential" streams layers (1.0 GiB, 34 s).
+OFFLOAD_MODES = ("auto", "none", "model", "sequential")
+
+
+def choose_offload(total_bytes):
+    return "none" if total_bytes >= 20 * 2**30 else "model" if total_bytes >= 10 * 2**30 else "sequential"
+
+
+class Engine:
+    def __init__(self, offload="auto"):
+        torch = require_cuda()
+        roots = hub.locate(COMPONENTS, DOWNLOAD_COMMAND)
+        from diffusers import AutoencoderKLFlux2, FlowMatchEulerDiscreteScheduler, Flux2KleinPipeline, Flux2Transformer2DModel
+        from safetensors.torch import load_file
+        from transformers import Qwen2Tokenizer, Qwen3Config, Qwen3ForCausalLM
+
+        root = roots["main"]
+        # Official single-file conversion of the original base weights. The Qwen encoder has native
+        # Transformers keys and tied embeddings: no custom node runtime.
+        transformer = Flux2Transformer2DModel.from_single_file(str(root / TRANSFORMER), config=str(root), subfolder="transformer",
+                                                               torch_dtype=torch.bfloat16, local_files_only=True)
+        encoder = Qwen3ForCausalLM.from_pretrained(None, config=Qwen3Config.from_pretrained(root / "text_encoder", local_files_only=True),
+                                                   state_dict=load_file(str(roots["encoder"] / ENCODER)), dtype=torch.bfloat16, local_files_only=True)
+        self.pipe = Flux2KleinPipeline(transformer=transformer, text_encoder=encoder,
+                                       tokenizer=Qwen2Tokenizer.from_pretrained(root / "tokenizer", local_files_only=True),
+                                       vae=AutoencoderKLFlux2.from_pretrained(root / "vae", torch_dtype=torch.bfloat16, local_files_only=True),
+                                       scheduler=FlowMatchEulerDiscreteScheduler.from_pretrained(root / "scheduler", local_files_only=True),
+                                       is_distilled=False)
+        self.pipe.load_lora_weights(str(roots["lora"]), weight_name=LORA, adapter_name="character", local_files_only=True)
+        self.pipe.set_adapters(["character"], adapter_weights=[1.0])
+        self.pipe.set_progress_bar_config(disable=True)  # stdout belongs to the MCP protocol in server mode
+        if offload == "auto":
+            offload = choose_offload(torch.cuda.get_device_properties(0).total_memory)
+        if offload == "model":
+            self.pipe.enable_model_cpu_offload()
+        elif offload == "sequential":
+            self.pipe.enable_sequential_cpu_offload()
+        else:
+            self.pipe.to("cuda")
+        self.torch, self.offload, self.lock = torch, offload, threading.Lock()
+        print(f"pixel sprite engine ready on {torch.cuda.get_device_name()} (offload: {offload})", file=sys.stderr, flush=True)
+
+    def render(self, description, reference, seed):
+        """One 512x512 raw sheet. `reference` is an RGB image or None."""
+        with self.lock:
+            try:
+                with self.torch.inference_mode():
+                    return self.pipe(**request_options(description, reference),
+                                     generator=self.torch.Generator("cuda").manual_seed(seed)).images[0]
+            except Exception:
+                # Return memory to the offload hooks so the next request starts clean.
+                self.pipe.maybe_free_model_hooks()
+                self.torch.cuda.empty_cache()
+                raise

mcpbytes_pixel_sprite/engine_exports.py

@@ -0,0 +1,54 @@
+"""Deterministic engine adapters from the same rectangles/timing used by PNG/GIF exports."""
+
+import json
+from pathlib import Path
+
+
+def engine_exports(manifest):
+    frames, animations = manifest["frames"], manifest["animations"]
+    ids = {frame["id"]: index for index, frame in enumerate(frames)}
+    resource = [f'[gd_resource type="SpriteFrames" load_steps={len(frames) + 2} format=3]',
+                '', '[ext_resource type="Texture2D" path="../sheet.png" id="1"]']
+    for index, frame in enumerate(frames):
+        rect = ", ".join(str(n) for n in frame["rect"])
+        resource.extend(['', f'[sub_resource type="AtlasTexture" id="Frame_{index}"]',
+                         'atlas = ExtResource("1")', f'region = Rect2({rect})', 'filter_clip = true'])
+    definitions = []
+    for name, animation in animations.items():
+        base = animation["durations_ms"][0]
+        sequence = ',\n'.join('{"duration": %.12g, "texture": SubResource("Frame_%d")}' % (duration / base, ids[frame])
+                              for frame, duration in zip(animation["frames"], animation["durations_ms"]))
+        definitions.append('{"frames": [\n%s\n], "loop": %s, "name": &%s, "speed": %.12g}' %
+                           (sequence, str(animation["loop"]).lower(), json.dumps(name), 1000 / base))
+    resource.extend(['', '[resource]', 'animations = [\n' + ',\n'.join(definitions) + '\n]'])
+    pivot = frames[0]["pivot"]
+    scene = f'''[gd_scene load_steps=2 format=3]
+
+[ext_resource type="SpriteFrames" path="sprite_frames.tres" id="1"]
+
+[node name="PixelCharacter" type="AnimatedSprite2D"]
+texture_filter = 1
+sprite_frames = ExtResource("1")
+animation = &"walk_down"
+autoplay = "walk_down"
+centered = false
+offset = Vector2({-pivot[0]}, {-pivot[1]})
+'''
+    height = manifest["size"][1]
+    unity_frames = []
+    for frame in frames:
+        x, y, w, h = frame["rect"]
+        unity_frames.append({"name": frame["id"], "rect": {"x": x, "y": height - y - h, "width": w, "height": h},
+                             "pivot": {"x": frame["pivot"][0] / w, "y": 1 - frame["pivot"][1] / h}})
+    unity = {"schema_version": 1, "sheet": "../sheet.png", "width": manifest["size"][0], "height": height,
+             "pixels_per_unit": manifest["cell_size"][1], "frames": unity_frames,
+             "animations": [{"name": name, "frames": animation["frames"], "durations_ms": animation["durations_ms"],
+                             "loop": animation["loop"]} for name, animation in animations.items()]}
+    return {
+        "godot/sprite_frames.tres": ("\n".join(resource) + "\n").encode(),
+        "godot/character.tscn": scene.encode(),
+        "unity/import.json": (json.dumps(unity, indent=2, allow_nan=False) + "\n").encode(),
+        # Keep the helper as text in each archive: multiple candidates must not install duplicate C# classes.
+        "unity/MCPBytesSpriteImporter.cs.txt": (Path(__file__).parent / "templates/MCPBytesSpriteImporter.cs.txt").read_bytes(),
+        "IMPORTING.md": (Path(__file__).parent / "templates/IMPORTING.md").read_bytes(),
+    }

mcpbytes_pixel_sprite/generate.py

@@ -0,0 +1,139 @@
+"""create_pixel_sprite, run locally or on the hosted API. Both write the same files into one folder:
+raw_N.png, sprite_N.png, sprite_N.json, sprite_N.zip per candidate N, and generation.json."""
+
+import hashlib
+import json
+import re
+import sys
+import uuid
+from importlib.metadata import version
+from pathlib import Path
+
+from PIL import Image
+
+from mcpbytes_core.errors import ToolError
+from mcpbytes_core.gpu import job_seed, stage_seed
+
+from .inference import VERSION as INFERENCE_VERSION, inference_hash
+from .models import COMPONENTS, MODEL_HASHES
+from .pipeline import VERSION as PROCESSING_VERSION, package
+
+TOOL = "create_pixel_sprite"
+PALETTE = re.compile(r"#[a-fA-F0-9]{6}(,#[a-fA-F0-9]{6}){1,63}")
+MAX_REFERENCE_PIXELS = 25_000_000  # the hosted tool's decoding bound
+
+
+def stderr(message):
+    print(message, file=sys.stderr, flush=True)
+
+
+def validate(options):
+    """Options with defaults applied, under the hosted tool's rules (create-pixel-sprite.ts), else invalid_options."""
+    def bad(message):
+        raise ToolError("invalid_options", message)
+
+    unknown = set(options) - {"description", "variants", "transparent", "palette_colors", "palette", "frame_duration_ms", "seed"}
+    if unknown:
+        bad(f"unknown options: {', '.join(sorted(unknown))}")
+    integer = lambda v: isinstance(v, int) and not isinstance(v, bool)  # noqa: E731
+    description = options.get("description")
+    if not isinstance(description, str) or not 1 <= len(description.strip()) <= 4000:
+        bad("description must be 1 to 4,000 characters")
+    result = {"description": description.strip(), "variants": options.get("variants", 1), "transparent": options.get("transparent", True),
+              "palette_colors": options.get("palette_colors", 32), "frame_duration_ms": options.get("frame_duration_ms", 120)}
+    if not integer(result["variants"]) or not 1 <= result["variants"] <= 4:
+        bad("variants must be 1 to 4")
+    if not isinstance(result["transparent"], bool):
+        bad("transparent must be true or false")
+    if result["palette_colors"] not in (16, 32, 64) or not integer(result["palette_colors"]):
+        bad("palette_colors must be 16, 32 or 64")
+    if not integer(result["frame_duration_ms"]) or not 40 <= result["frame_duration_ms"] <= 1000 or result["frame_duration_ms"] % 10:
+        bad("frame_duration_ms must be 40 to 1,000 in steps of 10")
+    if options.get("palette") is not None:
+        if not isinstance(options["palette"], str) or not PALETTE.fullmatch(options["palette"]):
+            bad("palette must be 2 to 64 comma-separated #RRGGBB colors without spaces")
+        result["palette"] = options["palette"]
+    if options.get("seed") is not None:
+        if not integer(options["seed"]) or not 0 <= options["seed"] <= 0xFFFFFFFF:
+            bad("seed must be an integer from 0 to 4294967295")
+        result["seed"] = options["seed"]
+    return result
+
+
+def prepare_output(out):
+    out = Path(out)
+    if out.exists() and (not out.is_dir() or any(out.iterdir())):
+        raise ToolError("output_exists", f"{out} is not an empty folder", "choose a new output folder; results are never overwritten")
+    out.mkdir(parents=True, exist_ok=True)
+    return out
+
+
+def load_reference(path):
+    """(RGB image at most 1024 px, its SHA-256), checked like the hosted tool's PNG/JPEG input."""
+    data = Path(path).read_bytes()
+    try:
+        with Image.open(Path(path)) as image:
+            if image.format not in ("PNG", "JPEG"):
+                raise ToolError("invalid_image", "the reference must be a PNG or JPEG")
+            if image.width * image.height > MAX_REFERENCE_PIXELS:
+                raise ToolError("invalid_image", "the reference must have at most 25 million pixels")
+            reference = image.convert("RGB")
+    except (OSError, Image.DecompressionBombError) as e:
+        raise ToolError("invalid_image", f"cannot read the reference image: {e}") from None
+    reference.thumbnail((1024, 1024), Image.Resampling.LANCZOS)
+    return reference, hashlib.sha256(data).hexdigest()
+
+
+def run_local(options, reference=None, out=".", engine=None, offload="auto", progress=stderr):
+    """Generate on this machine's GPU. Long-lived callers (the MCP server) pass a loaded `engine` to reuse."""
+    options = validate(options)
+    seed = job_seed(options.get("seed"))
+    image, reference_hash = load_reference(reference) if reference else (None, None)
+    out = prepare_output(out)
+    if engine is None:
+        from .engine import Engine
+
+        progress("Loading models")
+        engine = Engine(offload)
+    provenance = {"inference_version": INFERENCE_VERSION, "inference_sha256": inference_hash(bool(reference)),
+                  "model_revision": COMPONENTS["main"]["revision"], "reference_sha256": reference_hash,
+                  "source_revisions": [COMPONENTS[c]["revision"] for c in ("lora", "encoder")], "model_hashes": MODEL_HASHES,
+                  "runtime": f"mcpbytes-pixel-sprite {version('mcpbytes-pixel-sprite')}"}
+    stages = []
+    for number in range(1, options["variants"] + 1):
+        progress(f"Creating sprite {number} of {options['variants']}")
+        stage = {**options, "variant": number, "seed": stage_seed(seed, f"sprite_{number}")}
+        raw = engine.render(options["description"], image, stage["seed"])
+        stages.append(package(raw, out, stage, provenance))
+    settings = {k: v for k, v in options.items() if k != "description"}  # prompts stay out of generation.json, as in the cloud
+    (out / "generation.json").write_text(json.dumps({
+        "tool": TOOL, "runtime": "local", "options": {**settings, "seed": seed}, "inference_version": INFERENCE_VERSION,
+        "processing_version": PROCESSING_VERSION, "model_revisions": {c: s["revision"] for c, s in COMPONENTS.items()},
+        "stages": [{"stage_id": f"sprite_{s['variant']}", **s} for s in stages]}, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return summarize(out, stages, seed=seed)
+
+
+def run_cloud(options, reference=None, out=".", cloud=None, idempotency_key=None, progress=stderr):
+    """Generate on the hosted API for credits. Reuse `idempotency_key` after a lost response: no second charge."""
+    from mcpbytes_core.cloud import Cloud
+
+    options = validate(options)
+    cloud = cloud or Cloud()
+    out = prepare_output(out)
+    key = idempotency_key or str(uuid.uuid4())
+    progress(f"Request key {key}: reuse it with --idempotency-key if this run is interrupted")
+    upload_id = cloud.upload(reference) if reference else None
+    job = cloud.start(TOOL, options, key, upload_id)
+    progress(f"Job {job['id']}")
+    job = cloud.wait(job, lambda j: progress((j.get("workflow") or {}).get("stage") or j["status"]))
+    cloud.download(job, out)
+    stages = [json.loads((out / f"sprite_{n}.json").read_text(encoding="utf-8")) for n in range(1, options["variants"] + 1)]
+    return summarize(out, stages, job_id=job["id"], credits_charged=job.get("credits_charged"))
+
+
+def summarize(out, stages, **extra):
+    return {"qa_status": "needs_review" if any(s["qa_status"] == "needs_review" for s in stages) else "unreviewed",
+            "output_dir": str(out.resolve()), "files": sorted(p.name for p in out.iterdir()),
+            "variants": [{"variant": s["variant"], "sheet": f"sprite_{s['variant']}.png", "archive": f"sprite_{s['variant']}.zip",
+                          "qa_status": s["qa_status"], "warnings": s["warnings"]} for s in stages],
+            "notes": ["Review anatomy, direction, identity and transparency before using these sprites."], **extra}

mcpbytes_pixel_sprite/inference.py

@@ -0,0 +1,26 @@
+"""Versioned prompt/layout and fixed direct-pipeline settings, not caller-selected models."""
+
+import hashlib
+import json
+
+VERSION = "sprite_diffusers_v1"
+LAYOUT_PROMPT = (
+    "Four rows, four equal cells per row. Row one: three walking poses facing down, then arms raised. "
+    "Row two: three walking poses facing left, then a jumping-left still pose. "
+    "Row three: three walking poses facing right, then a jumping-right still pose. "
+    "Row four: three walking poses facing up, then a lying still pose. "
+    "One complete character in every cell, consistent identity and clothing. Leave space around every silhouette. "
+    "Plain solid magenta background (#ff00ff), no checkerboard, no lettering, no grid lines, no shadows. "
+    "Do not use magenta in the character."
+)
+
+
+def request_options(description, reference=None):
+    lead = "Pixel art spritesheet of the character in the reference. " if reference is not None else "Pixel art character spritesheet. "
+    return {"prompt": lead + description + ". " + LAYOUT_PROMPT, "image": reference,
+            "width": 512, "height": 512, "num_inference_steps": 20, "guidance_scale": 5.0, "num_images_per_prompt": 1}
+
+
+def inference_hash(reference=False):
+    settings = request_options("", "reference" if reference else None)
+    return hashlib.sha256(json.dumps({"version": VERSION, **settings}, sort_keys=True).encode()).hexdigest()

mcpbytes_pixel_sprite/models.py

@@ -0,0 +1,54 @@
+"""The exact Hugging Face files the hosted tool was qualified with (all Apache-2.0, ungated): about 16 GB.
+
+Revisions are commits, never branches. Sizes and SHA-256s were read from the Hub for these commits.
+"""
+
+COMPONENTS = {
+    "main": {
+        "repository": "black-forest-labs/FLUX.2-klein-base-4B",
+        "revision": "a3b4f4849157f664bdbc776fd7453c2783562f4d",
+        "files": {
+            "flux-2-klein-base-4b.safetensors": 7751105712,
+            "vae/config.json": 821,
+            "vae/diffusion_pytorch_model.safetensors": 168120878,
+            "LICENSE.md": 9584,
+            "README.md": 10084,
+            "model_index.json": 422,
+            "transformer/config.json": 531,
+            "text_encoder/config.json": 1536,
+            "text_encoder/generation_config.json": 214,
+            "scheduler/scheduler_config.json": 486,
+            "tokenizer/added_tokens.json": 707,
+            "tokenizer/chat_template.jinja": 4168,
+            "tokenizer/merges.txt": 1671853,
+            "tokenizer/special_tokens_map.json": 613,
+            "tokenizer/tokenizer.json": 11422654,
+            "tokenizer/tokenizer_config.json": 5404,
+            "tokenizer/vocab.json": 2776833,
+        },
+    },
+    "lora": {
+        "repository": "svntax-dev/pixel_spritesheet_4walk_small_lora_v1",
+        "revision": "cb8bffe5b9b92e656e31e7f940ec4a38047d6a88",
+        "files": {"pixel_4walk_small_flux2_klein_base_4b_v1.safetensors": 92426736, "README.md": 6181},
+    },
+    "encoder": {
+        "repository": "Comfy-Org/z_image_turbo",
+        "revision": "6fc90a3b1b653e935a0d175e260736de25b84df5",
+        "files": {"split_files/text_encoders/qwen_3_4b.safetensors": 8044982048, "README.md": 4785},
+    },
+}
+
+TRANSFORMER = "flux-2-klein-base-4b.safetensors"
+LORA = "pixel_4walk_small_flux2_klein_base_4b_v1.safetensors"
+ENCODER = "split_files/text_encoders/qwen_3_4b.safetensors"
+
+# Weight hashes, recorded in each export's provenance.json as the hosted tool does.
+MODEL_HASHES = sorted([
+    "9c5fed22b76baea749d88fc2abe3ad53245e7b21a0d353a762665eea00043b92",  # main transformer
+    "ca70d2202afe6415bdbcb8793ba8cd99fd159cfe6192381504d6c4d3036e0f04",  # main VAE
+    "a968c042c2443bf6bfed41ce833a0e06bf5bbb7961ac40b88fb7257a940ae54e",  # LoRA
+    "6c671498573ac2f7a5501502ccce8d2b08ea6ca2f661c458e708f36b36edfc5a",  # Qwen3 encoder
+])
+
+DOWNLOAD_COMMAND = "mcpbytes-pixel-sprite download"