constellai 0.3.0

package/skills/design/pet-companion-codex-companion-contract-reference-guide/scripts/inspect_frames.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""Inspect extracted Codex pet frames before atlas composition."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from pathlib import Path
+from statistics import median
+
+from PIL import Image
+
+CELL_WIDTH = 192
+CELL_HEIGHT = 208
+ROW_FRAME_COUNTS = {
+    "idle": 6,
+    "running-right": 8,
+    "running-left": 8,
+    "waving": 4,
+    "jumping": 5,
+    "failed": 8,
+    "waiting": 6,
+    "running": 6,
+    "review": 6,
+}
+IMAGE_SUFFIXES = {".png", ".webp", ".jpg", ".jpeg"}
+
+
+def alpha_nonzero_count(image: Image.Image) -> int:
+    alpha = image if image.mode == "L" else image.getchannel("A")
+    return sum(alpha.histogram()[1:])
+
+
+def edge_alpha_count(image: Image.Image, margin: int) -> int:
+    alpha = image.getchannel("A")
+    width, height = alpha.size
+    total = 0
+    for box in (
+        (0, 0, width, margin),
+        (0, height - margin, width, height),
+        (0, 0, margin, height),
+        (width - margin, 0, width, height),
+    ):
+        total += alpha_nonzero_count(alpha.crop(box))
+    return total
+
+
+def color_distance(left: tuple[int, int, int], right: tuple[int, int, int]) -> float:
+    return math.sqrt(sum((left[index] - right[index]) ** 2 for index in range(3)))
+
+
+def chroma_adjacent_count(
+    image: Image.Image,
+    chroma_key: tuple[int, int, int] | None,
+    threshold: float,
+) -> int:
+    if chroma_key is None:
+        return 0
+    rgba = image.convert("RGBA")
+    data = rgba.tobytes()
+    count = 0
+    for index in range(0, len(data), 4):
+        red, green, blue, alpha = data[index : index + 4]
+        if alpha > 16 and color_distance((red, green, blue), chroma_key) <= threshold:
+            count += 1
+    return count
+
+
+def frame_files(state_dir: Path) -> list[Path]:
+    if not state_dir.is_dir():
+        return []
+    return sorted(path for path in state_dir.iterdir() if path.suffix.lower() in IMAGE_SUFFIXES)
+
+
+def load_manifest(frames_root: Path) -> dict[str, dict[str, object]]:
+    manifest_path = frames_root / "frames-manifest.json"
+    if not manifest_path.is_file():
+        return {}
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    rows = manifest.get("rows", [])
+    if not isinstance(rows, list):
+        return {}
+    return {
+        row["state"]: row
+        for row in rows
+        if isinstance(row, dict) and isinstance(row.get("state"), str)
+    }
+
+
+def load_chroma_key(frames_root: Path) -> tuple[int, int, int] | None:
+    manifest_path = frames_root / "frames-manifest.json"
+    if not manifest_path.is_file():
+        return None
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    chroma_key = manifest.get("chroma_key")
+    if not isinstance(chroma_key, dict):
+        return None
+    rgb = chroma_key.get("rgb")
+    if (
+        not isinstance(rgb, list)
+        or len(rgb) != 3
+        or not all(isinstance(value, int) for value in rgb)
+    ):
+        return None
+    return (rgb[0], rgb[1], rgb[2])
+
+
+def inspect_state(
+    frames_root: Path,
+    state: str,
+    expected_count: int,
+    manifest_rows: dict[str, dict[str, object]],
+    chroma_key: tuple[int, int, int] | None,
+    args: argparse.Namespace,
+) -> dict[str, object]:
+    state_dir = frames_root / state
+    files = frame_files(state_dir)
+    row_errors: list[str] = []
+    row_warnings: list[str] = []
+    frames: list[dict[str, object]] = []
+    areas: list[int] = []
+    manifest_row = manifest_rows.get(state, {})
+    method = manifest_row.get("method")
+
+    if len(files) != expected_count:
+        row_errors.append(f"expected {expected_count} frame files for {state}, found {len(files)}")
+
+    if args.require_components and method and method != "components":
+        row_errors.append(
+            f"{state} used extraction method {method}; regenerate the row or inspect slot slicing"
+        )
+    elif method and method != "components":
+        row_warnings.append(
+            f"{state} used extraction method {method}; component extraction is preferred"
+        )
+
+    for index, frame_path in enumerate(files[:expected_count]):
+        with Image.open(frame_path) as opened:
+            frame = opened.convert("RGBA")
+        nontransparent = alpha_nonzero_count(frame)
+        bbox = frame.getbbox()
+        edge_pixels = edge_alpha_count(frame, args.edge_margin)
+        chroma_adjacent_pixels = chroma_adjacent_count(
+            frame,
+            chroma_key,
+            args.chroma_adjacent_threshold,
+        )
+        info = {
+            "index": index,
+            "file": str(frame_path),
+            "width": frame.width,
+            "height": frame.height,
+            "nontransparent_pixels": nontransparent,
+            "bbox": list(bbox) if bbox else None,
+            "edge_pixels": edge_pixels,
+            "chroma_adjacent_pixels": chroma_adjacent_pixels,
+        }
+        frames.append(info)
+        areas.append(nontransparent)
+
+        if frame.size != (CELL_WIDTH, CELL_HEIGHT):
+            row_errors.append(
+                f"{state} frame {index:02d} is {frame.width}x{frame.height}; expected {CELL_WIDTH}x{CELL_HEIGHT}"
+            )
+        if nontransparent < args.min_used_pixels:
+            row_errors.append(
+                f"{state} frame {index:02d} is empty or too sparse ({nontransparent} pixels)"
+            )
+        if edge_pixels > args.edge_pixel_threshold:
+            row_warnings.append(
+                f"{state} frame {index:02d} has {edge_pixels} non-transparent pixels near the cell edge"
+            )
+        if chroma_adjacent_pixels > args.chroma_adjacent_pixel_threshold:
+            row_errors.append(
+                f"{state} frame {index:02d} has {chroma_adjacent_pixels} non-transparent pixels close to the chroma key"
+            )
+
+    if areas:
+        row_median = median(areas)
+        for index, area in enumerate(areas[:expected_count]):
+            if row_median > 0 and area < row_median * args.small_outlier_ratio:
+                row_warnings.append(
+                    f"{state} frame {index:02d} is much smaller than the row median ({area} vs {row_median:.0f})"
+                )
+            if row_median > 0 and area > row_median * args.large_outlier_ratio:
+                row_warnings.append(
+                    f"{state} frame {index:02d} is much larger than the row median ({area} vs {row_median:.0f})"
+                )
+
+    return {
+        "state": state,
+        "expected_frames": expected_count,
+        "actual_frames": len(files),
+        "extraction_method": method,
+        "ok": not row_errors,
+        "errors": row_errors,
+        "warnings": row_warnings,
+        "frames": frames,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--frames-root", required=True)
+    parser.add_argument("--json-out", required=True)
+    parser.add_argument("--min-used-pixels", type=int, default=400)
+    parser.add_argument("--edge-margin", type=int, default=2)
+    parser.add_argument("--edge-pixel-threshold", type=int, default=24)
+    parser.add_argument("--chroma-adjacent-threshold", type=float, default=150.0)
+    parser.add_argument("--chroma-adjacent-pixel-threshold", type=int, default=800)
+    parser.add_argument("--small-outlier-ratio", type=float, default=0.35)
+    parser.add_argument("--large-outlier-ratio", type=float, default=2.75)
+    parser.add_argument(
+        "--require-components",
+        action="store_true",
+        help="Fail rows that fell back to equal-slot extraction.",
+    )
+    args = parser.parse_args()
+
+    frames_root = Path(args.frames_root).expanduser().resolve()
+    manifest_rows = load_manifest(frames_root)
+    chroma_key = load_chroma_key(frames_root)
+    rows = [
+        inspect_state(frames_root, state, count, manifest_rows, chroma_key, args)
+        for state, count in ROW_FRAME_COUNTS.items()
+    ]
+    errors = [error for row in rows for error in row["errors"]]
+    warnings = [warning for row in rows for warning in row["warnings"]]
+    result = {
+        "ok": not errors,
+        "frames_root": str(frames_root),
+        "errors": errors,
+        "warnings": warnings,
+        "rows": rows,
+    }
+
+    json_out = Path(args.json_out).expanduser().resolve()
+    json_out.parent.mkdir(parents=True, exist_ok=True)
+    json_out.write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps({k: v for k, v in result.items() if k != "rows"}, indent=2))
+    raise SystemExit(0 if result["ok"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/design/pet-companion-codex-companion-contract-reference-guide/scripts/make_contact_sheet.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Create a labeled contact sheet from a Codex pet atlas."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+COLUMNS = 8
+ROWS = 9
+CELL_WIDTH = 192
+CELL_HEIGHT = 208
+LABEL_HEIGHT = 22
+ROW_NAMES = [
+    "idle",
+    "running-right",
+    "running-left",
+    "waving",
+    "jumping",
+    "failed",
+    "waiting",
+    "running",
+    "review",
+]
+USED_COUNTS = [6, 8, 8, 4, 5, 8, 6, 6, 6]
+
+
+def checker(size: tuple[int, int], square: int = 16) -> Image.Image:
+    image = Image.new("RGB", size, "#ffffff")
+    draw = ImageDraw.Draw(image)
+    for y in range(0, size[1], square):
+        for x in range(0, size[0], square):
+            if (x // square + y // square) % 2:
+                draw.rectangle((x, y, x + square - 1, y + square - 1), fill="#e8e8e8")
+    return image
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("atlas")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--scale", type=float, default=0.5)
+    args = parser.parse_args()
+
+    with Image.open(Path(args.atlas).expanduser().resolve()) as opened:
+        atlas = opened.convert("RGBA")
+
+    cell_w = max(1, round(CELL_WIDTH * args.scale))
+    cell_h = max(1, round(CELL_HEIGHT * args.scale))
+    width = COLUMNS * cell_w
+    height = ROWS * (cell_h + LABEL_HEIGHT)
+    sheet = Image.new("RGB", (width, height), "#f7f7f7")
+    draw = ImageDraw.Draw(sheet)
+    font = ImageFont.load_default()
+
+    for row in range(ROWS):
+        y = row * (cell_h + LABEL_HEIGHT)
+        draw.rectangle((0, y, width, y + LABEL_HEIGHT - 1), fill="#111111")
+        draw.text((6, y + 5), f"row {row}: {ROW_NAMES[row]}", fill="#ffffff", font=font)
+        draw.text(
+            (width - 92, y + 5),
+            f"{USED_COUNTS[row]} frames",
+            fill="#ffffff",
+            font=font,
+        )
+        for column in range(COLUMNS):
+            crop = atlas.crop(
+                (
+                    column * CELL_WIDTH,
+                    row * CELL_HEIGHT,
+                    (column + 1) * CELL_WIDTH,
+                    (row + 1) * CELL_HEIGHT,
+                )
+            )
+            crop = crop.resize((cell_w, cell_h), Image.Resampling.LANCZOS)
+            bg = checker((cell_w, cell_h))
+            bg.paste(crop, (0, 0), crop)
+            x = column * cell_w
+            sheet.paste(bg, (x, y + LABEL_HEIGHT))
+            outline = "#18a058" if column < USED_COUNTS[row] else "#cc3344"
+            draw.rectangle(
+                (x, y + LABEL_HEIGHT, x + cell_w - 1, y + LABEL_HEIGHT + cell_h - 1),
+                outline=outline,
+            )
+            draw.text((x + 4, y + LABEL_HEIGHT + 4), str(column), fill="#111111", font=font)
+
+    output = Path(args.output).expanduser().resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(output)
+    print(f"wrote {output}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/design/pet-companion-codex-companion-contract-reference-guide/scripts/package_custom_pet.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Package a validated atlas as a local Codex pet."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+from pathlib import Path
+
+from PIL import Image
+
+ATLAS_SIZE = (1536, 1872)
+
+
+def default_codex_home() -> Path:
+    return Path(os.environ.get("CODEX_HOME") or "~/.codex").expanduser().resolve()
+
+
+def slugify(value: str) -> str:
+    value = value.strip().lower()
+    value = re.sub(r"[^a-z0-9]+", "-", value)
+    value = re.sub(r"-{2,}", "-", value)
+    return value.strip("-")
+
+
+def validate_spritesheet(path: Path) -> str:
+    with Image.open(path) as image:
+        if image.size != ATLAS_SIZE:
+            raise SystemExit(
+                f"expected {ATLAS_SIZE[0]}x{ATLAS_SIZE[1]}, got {image.width}x{image.height}"
+            )
+        if image.format not in {"PNG", "WEBP"}:
+            raise SystemExit(f"expected PNG or WebP, got {image.format}")
+        return str(image.format)
+
+
+def write_webp_spritesheet(source: Path, target: Path, source_format: str) -> None:
+    if source_format == "WEBP":
+        shutil.copy2(source, target)
+        return
+    with Image.open(source) as image:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        image.convert("RGBA").save(
+            target,
+            format="WEBP",
+            lossless=True,
+            quality=100,
+            method=6,
+        )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pet-name", default="")
+    parser.add_argument("--display-name", default="")
+    parser.add_argument("--description", required=True)
+    parser.add_argument("--spritesheet", required=True)
+    parser.add_argument("--codex-home", default=str(default_codex_home()))
+    parser.add_argument(
+        "--output-dir",
+        help="Exact pet package directory. Defaults to ${CODEX_HOME:-$HOME/.codex}/pets/<pet-name>.",
+    )
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+
+    raw_pet_name = (args.pet_name or args.display_name).strip()
+    if not raw_pet_name:
+        raise SystemExit("pet name is required")
+    pet_id = slugify(raw_pet_name)
+    if not pet_id:
+        raise SystemExit("pet name must contain at least one letter or digit")
+    display_name = (args.display_name or raw_pet_name).strip()
+
+    source = Path(args.spritesheet).expanduser().resolve()
+    source_format = validate_spritesheet(source)
+    target_dir = (
+        Path(args.output_dir).expanduser().resolve()
+        if args.output_dir
+        else Path(args.codex_home).expanduser().resolve() / "pets" / pet_id
+    )
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    target_sheet = target_dir / "spritesheet.webp"
+    manifest_path = target_dir / "pet.json"
+    if not args.force and (target_sheet.exists() or manifest_path.exists()):
+        raise SystemExit(f"{target_dir} already contains pet files; pass --force to overwrite")
+
+    write_webp_spritesheet(source, target_sheet, source_format)
+    manifest = {
+        "id": pet_id,
+        "displayName": display_name,
+        "description": args.description,
+        "spritesheetPath": target_sheet.name,
+    }
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+    print(
+        json.dumps(
+            {"ok": True, "pet_dir": str(target_dir), "manifest": str(manifest_path)}, indent=2
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

package/skills/design/pet-companion-codex-companion-contract-reference-guide/scripts/pet_job_status.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Show ready and pending $imagegen jobs for a Codex pet run."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+
+def load_manifest(run_dir: Path) -> dict[str, object]:
+    path = run_dir / "imagegen-jobs.json"
+    if not path.exists():
+        raise SystemExit(f"job manifest not found: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def jobs(manifest: dict[str, object]) -> list[dict[str, object]]:
+    raw = manifest.get("jobs")
+    if not isinstance(raw, list):
+        raise SystemExit("invalid imagegen-jobs.json: jobs must be a list")
+    return [job for job in raw if isinstance(job, dict)]
+
+
+def completed_ids(manifest: dict[str, object]) -> set[str]:
+    return {
+        str(job["id"])
+        for job in jobs(manifest)
+        if job.get("status") == "complete" and isinstance(job.get("id"), str)
+    }
+
+
+def missing_deps(job: dict[str, object], completed: set[str]) -> list[str]:
+    deps = job.get("depends_on", [])
+    if not isinstance(deps, list):
+        return []
+    return [dep for dep in deps if isinstance(dep, str) and dep not in completed]
+
+
+def job_view(
+    job: dict[str, object], run_dir: Path, completed: set[str]
+) -> dict[str, object]:
+    prompt_file = job.get("prompt_file")
+    output_path = job.get("output_path")
+    inputs = (
+        job.get("input_images") if isinstance(job.get("input_images"), list) else []
+    )
+    input_images = []
+    for item in inputs:
+        path = (
+            run_dir / item["path"]
+            if isinstance(item, dict) and isinstance(item.get("path"), str)
+            else None
+        )
+        input_images.append(
+            {
+                "path": str(path) if path else None,
+                "role": item.get("role") if isinstance(item, dict) else None,
+                "exists": path.is_file() if path else False,
+            }
+        )
+    return {
+        "id": job.get("id"),
+        "kind": job.get("kind"),
+        "status": job.get("status", "pending"),
+        "prompt_file": str(run_dir / prompt_file)
+        if isinstance(prompt_file, str)
+        else None,
+        "input_images": input_images,
+        "output_path": str(run_dir / output_path)
+        if isinstance(output_path, str)
+        else None,
+        "missing_dependencies": missing_deps(job, completed),
+        "repair_attempt": job.get("repair_attempt", 0),
+        "generation_skill": job.get("generation_skill"),
+        "requires_grounded_generation": job.get("requires_grounded_generation", False),
+        "allow_prompt_only_generation": job.get("allow_prompt_only_generation", False),
+        "identity_reference_paths": job.get("identity_reference_paths", []),
+        "mirror_policy": job.get("mirror_policy", {}),
+        "derived_from": job.get("derived_from"),
+        "source_provenance": job.get("source_provenance"),
+        "mirror_decision": job.get("mirror_decision"),
+        "recording_owner": job.get("recording_owner", "parent"),
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-dir", required=True)
+    args = parser.parse_args()
+
+    run_dir = Path(args.run_dir).expanduser().resolve()
+    manifest = load_manifest(run_dir)
+    completed = completed_ids(manifest)
+    pending = [
+        job for job in jobs(manifest) if job.get("status", "pending") != "complete"
+    ]
+    ready = [job for job in pending if not missing_deps(job, completed)]
+    blocked = [job for job in pending if missing_deps(job, completed)]
+
+    result = {
+        "ok": True,
+        "run_dir": str(run_dir),
+        "counts": {
+            "total": len(jobs(manifest)),
+            "complete": len(completed),
+            "ready": len(ready),
+            "blocked": len(blocked),
+        },
+        "ready_jobs": [job_view(job, run_dir, completed) for job in ready],
+        "blocked_jobs": [job_view(job, run_dir, completed) for job in blocked],
+    }
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()