spriteforge 0.1.1__py3-none-any.whl

spriteforge/library/cli.py

@@ -0,0 +1,126 @@
+"""`spriteforge library ...`: ingest downloaded packs and browse the catalog."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from . import store
+
+app = typer.Typer(no_args_is_help=True, help="Third-party asset library with license tracking.")
+
+
+def _cell(value: str) -> tuple[int, int] | str | None:
+    if not value:
+        return None
+    if value == "auto":
+        return "auto"
+    w, _, h = value.lower().partition("x")
+    return int(w), int(h or w)
+
+
+@app.command()
+def add(
+    source: Path,
+    pack: Annotated[str, typer.Option(help="Pack id, e.g. kenney-tiny-dungeon.")],
+    category: Annotated[str, typer.Option(help="character/enemy/tileset/item/...")] = "other",
+    subcategory: str = "",
+    title: str = "",
+    tag: Annotated[list[str] | None, typer.Option(help="Extra tag (repeatable).")] = None,
+    cell: Annotated[str, typer.Option(help="Grid cell for sheets, e.g. 16x16.")] = "",
+    author: str = "unknown",
+    source_url: str = "",
+    license: Annotated[str, typer.Option(help="CC0, CC-BY-4.0, ... or UNKNOWN.")] = "UNKNOWN",
+    license_url: str = "",
+    verified: Annotated[bool, typer.Option(help="License checked on the source page.")] = False,
+    notes: str = "",
+):
+    """Add a downloaded .zip, folder or image to assets/library/."""
+    result = store.add_pack(
+        source, pack, title=title, category=category, subcategory=subcategory, tags=tag or [],
+        cell=_cell(cell), author=author, source_url=source_url, license=license,
+        license_url=license_url, license_verified=verified, notes=notes,
+    )  # fmt: skip
+    typer.echo(f"{result.id}: {len(result.assets)} assets, usage={result.usage}")
+    if result.usage == "reference-only":
+        typer.echo("  License not verified: builds will not ship this art. Use `library license`.")
+
+
+@app.command("list")
+def list_cmd():
+    """Show packs with their license status."""
+    for p in store.load_packs():
+        typer.echo(f"{p.id:32} {len(p.assets):4} assets  {p.license:12} {p.usage}")
+
+
+@app.command()
+def search(category: str = "", tag: str = "", cell: str = "", usage: str = ""):
+    """Find assets, e.g. --category equipment --tag chainmail --usage ship."""
+    for a in store.search(category=category, tag=tag, size=_cell(cell), usage=usage):
+        typer.echo(f"{a['id']:44} {a['cell'][0]}x{a['cell'][1]}  {a['usage']:16} {a['file']}")
+
+
+@app.command()
+def describe(
+    pack: Annotated[list[str] | None, typer.Option(help="Only this pack (repeatable).")] = None,
+    force: Annotated[bool, typer.Option(help="Describe again what is already described.")] = False,
+    mock: Annotated[bool, typer.Option(help="Offline: measured looks only, no model.")] = False,
+    max_calls: Annotated[int, typer.Option(help="Cap on Muse Spark calls.")] = 30,
+    max_cost: Annotated[float, typer.Option(help="Cap on the estimated cost, USD.")] = 0.5,
+    config: Path | None = None,
+    workspace: Path | None = None,
+):
+    """Describe every library image: a measured look (colours, brightness, detail) for all,
+    and a Muse Spark (vision) description for packs that allow AI use."""
+    from spriteforge.config import BudgetConfig, init_workspace, load_config
+    from spriteforge.core.cost import Budget
+    from spriteforge.core.credentials import load_credentials
+    from spriteforge.core.state import Store
+    from spriteforge.providers.muse_spark import MuseSparkProvider
+
+    from .describe import describe_library
+
+    cfg = load_config(config)
+    provider, budget = None, None
+    if not mock:
+        load_credentials()
+        root = init_workspace(workspace or cfg.workspace)
+        store = Store(root / "library.sqlite3")
+        cap = BudgetConfig(**{**cfg.budget.model_dump(), "max_calls_per_model": max_calls,
+                              "max_estimated_cost": max_cost})  # fmt: skip
+        run = store.create_run({"workflow": "library-describe", "budget": cap.model_dump()})
+        budget = Budget(store, run.id, cap)
+        provider = MuseSparkProvider(cfg.llm, budget)
+    counts = describe_library(provider=provider, model=cfg.llm.model if provider else "",
+                              reasoning=cfg.llm.reasoning.get("describe"), packs=pack or None,
+                              force=force, log=typer.echo)  # fmt: skip
+    if provider is not None:
+        provider.close()
+    typer.echo(
+        f"{counts['model']} described by the model, {counts['measured']} measured only, "
+        f"{counts['kept']} unchanged, {counts['failed']} not described"
+        + (f"; about ${budget.spent():.3f}" if budget else "")
+    )
+
+
+@app.command()
+def mcp():
+    """Expose read-only library tools (packs, search, actors, tile sets) over MCP stdio."""
+    from spriteforge.mcp.library import create_server
+
+    create_server().run(transport="stdio")
+
+
+@app.command()
+def license(
+    pack: str,
+    license: str,
+    source_url: str = "",
+    license_url: str = "",
+    author: str = "",
+):
+    """Record a license you checked on the pack's download page (marks it verified)."""
+    p = store.set_license(
+        pack, license, source_url=source_url, license_url=license_url, author=author
+    )
+    typer.echo(f"{p.id}: license={p.license} usage={p.usage}")

spriteforge/library/describe.py

@@ -0,0 +1,242 @@
+"""Descriptions of every library image, so the harness can choose art by what it shows.
+
+`describe_library` gives every asset, and every named tile of an installed tile set, a measured
+look (`looks.measure`: colours, brightness, detail; free). Images from packs that allow AI use
+are also described by Muse Spark (vision): numbered contact sheets of up to 16 images, one
+call each, answering what each image is, one sentence on what it shows and the camera it is
+drawn for. Packs whose license forbids AI use never reach a model: their entry is the file
+name and the measured look.
+
+Entries are written to `<library>/descriptions/<pack>.json` (`{"assets": {id: entry},
+"tiles": {tile id: entry}}`) with the image's sha256, so a changed image is described again
+and an unchanged one is not sent twice. Model-written entries are `status: generated`; edit
+the text, set `status: reviewed`, and later runs keep it. `rebuild_index` merges the entries
+into index.json, so `search()` (the art step, the MCP tools, the catalog) returns them.
+"""
+
+import hashlib
+import io
+import json
+import math
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from PIL import Image, ImageDraw, ImageFont
+from pydantic import Field
+
+from spriteforge.agents.models import Contract
+from spriteforge.core.cost import BudgetExceeded
+from spriteforge.providers.base import ChatRequest, LLMProvider, Message, chat_json
+
+from .looks import Look, asset_image, measure
+from .store import library_root, load_descriptions, load_packs, rebuild_index
+
+PER_SHEET = 16
+CELL = 128  # px per image on the contact sheet
+LABEL = 18
+SHEET_BACKGROUND = (128, 128, 132, 255)
+View = Literal["top-down", "3/4 top-down", "side", "front", "flat", "unknown"]
+
+
+class Seen(Contract):
+    n: int = Field(description="the image's number on the sheet")
+    what: str = Field(description="what it is, 1-4 words, e.g. 'hooded rogue', 'stone floor tile'")
+    description: str = Field(
+        description="one sentence, at most 30 words: the subject, its main colours by name and "
+        "whether it is light or dark, and the details that matter when choosing game art"
+    )
+    view: View = Field(description="the camera the art is drawn for")
+
+
+class SheetAnswer(Contract):
+    images: list[Seen]
+
+
+@dataclass
+class Item:
+    key: str  # asset id, or tile id (`<tileset>/<tile>`)
+    section: Literal["assets", "tiles"]
+    pack: str
+    name: str
+    category: str
+    image: Image.Image
+    sha256: str
+    ai_allowed: bool
+    hint: str  # size and frames, for the prompt
+
+
+def library_items(root: Path, packs: list[str] | None = None) -> list[Item]:
+    """Every asset (an animation sheet as its first frame) and every named tile of the
+    installed tile sets, in a stable order."""
+    from spriteforge.game.tilesets import load_tilesets, tile_image
+
+    items = []
+    installed = {p.id: p for p in load_packs(root) if not packs or p.id in packs}
+    for pack in installed.values():
+        for a in pack.assets:
+            asset = a.model_dump(mode="json")
+            frames = f", {a.frames} frames of {a.cell[0]}x{a.cell[1]}" if a.frames > 1 else ""
+            items.append(Item(a.id, "assets", pack.id, a.name, a.category,
+                              asset_image(asset, root), a.sha256, pack.ai_allowed,
+                              f"{a.size[0]}x{a.size[1]}{frames}"))  # fmt: skip
+    for ts in load_tilesets():
+        if ts["pack"] not in installed:
+            continue
+        for name, spec in ts["tiles"].items():
+            tile = tile_image(ts, name)
+            buf = io.BytesIO()
+            tile.save(buf, format="PNG")
+            items.append(Item(f"{ts['id']}/{name}", "tiles", ts["pack"], spec["what"], "tile",
+                              tile, hashlib.sha256(buf.getvalue()).hexdigest(),
+                              installed[ts["pack"]].ai_allowed,
+                              f"one {ts['tile_size']} px tile of a {ts['camera']} tile set"))  # fmt: skip
+    return items
+
+
+def measured_entry(item: Item, look: Look) -> dict:
+    return {
+        "sha256": item.sha256,
+        "what": item.name,
+        "text": f"{item.name} ({item.category}); {look.text}",
+        "view": "unknown",
+        "look": look.model_dump(),
+        "by": "measured",
+        "status": "measured",
+    }
+
+
+def contact_sheet(items: list[Item]) -> bytes:
+    """Numbered cells of CELL px on a neutral grey; pixel art scaled by whole numbers."""
+    cols = min(4, len(items))
+    rows = math.ceil(len(items) / cols)
+    step = CELL + LABEL
+    sheet = Image.new("RGBA", (cols * CELL, rows * step), SHEET_BACKGROUND)
+    draw = ImageDraw.Draw(sheet)
+    font = ImageFont.load_default(size=LABEL - 4)
+    for n, item in enumerate(items):
+        image = item.image
+        if bbox := image.getchannel("A").getbbox():
+            image = image.crop(bbox)
+        side = max(image.size)
+        if side > CELL - 8:
+            k = math.ceil(side / (CELL - 8))
+            image = image.resize(
+                (max(1, image.width // k), max(1, image.height // k)), Image.Resampling.NEAREST
+            )
+        else:
+            k = max(1, (CELL - 8) // side)
+            image = image.resize((image.width * k, image.height * k), Image.Resampling.NEAREST)
+        x, y = (n % cols) * CELL, (n // cols) * step
+        draw.text((x + 4, y + 1), str(n + 1), fill=(255, 255, 255, 255), font=font)
+        sheet.alpha_composite(
+            image, (x + (CELL - image.width) // 2, y + LABEL + (CELL - image.height) // 2)
+        )
+    buf = io.BytesIO()
+    sheet.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def sheet_prompt(items: list[Item]) -> str:
+    listed = "\n".join(
+        f'{n}. "{item.name}" ({item.category}, {item.hint})' for n, item in enumerate(items, 1)
+    )
+    return (
+        f"The image is a contact sheet of {len(items)} numbered pixel-art images from a game "
+        "art library, each enlarged with square pixels on a neutral grey (an animation sheet "
+        "shows its first frame; a tile set shows its whole sheet). For every number, say what "
+        "the image shows, judged from its pixels: `what` in 1-4 words, `description` in one "
+        "sentence of at most 30 words (the subject, its main colours by name and whether it is "
+        "light or dark, and the details that matter when choosing art for a game), and `view` "
+        "(the camera it is drawn for). The names below come from file names: they are hints "
+        "and may be wrong or cryptic; trust the pixels.\n\n" + listed
+    )
+
+
+def role_text() -> str:
+    from spriteforge.agents.roles import load_roles
+
+    r = load_roles()["Librarian"]
+    return f"You are the {r.name} of a small game studio. Goal: {r.goal}\n{r.prompt}"
+
+
+def describe_library(
+    root: Path | None = None,
+    provider: LLMProvider | None = None,
+    *,
+    model: str = "",
+    reasoning: str | None = None,
+    packs: list[str] | None = None,
+    force: bool = False,
+    per_sheet: int = PER_SHEET,
+    log: Callable[[str], None] = print,
+) -> dict:
+    """Describe the library (see the module doc). Without a `provider` only measured looks
+    are written. A failed sheet keeps measured entries for its images; running out of budget
+    stops the model calls. Returns counts."""
+    root = library_root(root)
+    old = load_descriptions(root)
+    items = library_items(root, packs)
+    out: dict[str, dict] = {p: {"assets": {}, "tiles": {}} for p in {i.pack for i in items}}
+    for pack, data in old.items():  # packs not described this time keep their file as is
+        out.setdefault(pack, data)
+    todo: list[Item] = []
+    counts = {"model": 0, "measured": 0, "kept": 0, "failed": 0, "sheets": 0}
+    for item in items:
+        look = measure(item.image)
+        prev = old.get(item.pack, {}).get(item.section, {}).get(item.key)
+        same = prev is not None and prev.get("sha256") == item.sha256
+        if same and (prev["status"] == "reviewed" or (prev["by"] != "measured" and not force)):
+            out[item.pack][item.section][item.key] = {**prev, "look": look.model_dump()}
+            counts["kept"] += 1
+            continue
+        out[item.pack][item.section][item.key] = measured_entry(item, look)
+        if item.ai_allowed and provider is not None:
+            todo.append(item)
+        else:
+            counts["measured"] += 1
+    batches = [todo[i : i + per_sheet] for i in range(0, len(todo), per_sheet)]
+    for number, batch in enumerate(batches, 1):
+        request = ChatRequest(
+            messages=[
+                Message(role="system", content=role_text()),
+                Message(role="user", content=sheet_prompt(batch), images=[contact_sheet(batch)]),
+            ],
+            reasoning_effort=reasoning,
+            cache_key="spriteforge-describe",
+        )
+        try:
+            counts["sheets"] += 1
+            answer = chat_json(provider, request, SheetAnswer)
+        except BudgetExceeded as exc:
+            log(f"  sheet {number}/{len(batches)}: {exc}; the rest keep measured entries")
+            counts["failed"] += sum(len(b) for b in batches[number - 1 :])
+            break
+        except Exception as exc:  # noqa: BLE001 -- one bad sheet must not lose the others
+            log(f"  sheet {number}/{len(batches)} failed ({type(exc).__name__}: {exc})"[:300])
+            counts["failed"] += len(batch)
+            continue
+        seen = {s.n: s for s in answer.images if 1 <= s.n <= len(batch)}
+        for n, item in enumerate(batch, 1):
+            if n not in seen:
+                counts["failed"] += 1
+                continue
+            s = seen[n]
+            entry = out[item.pack][item.section][item.key]
+            entry.update(what=s.what.strip(), text=s.description.strip(), view=s.view,
+                         by=model or "model", status="generated")  # fmt: skip
+            counts["model"] += 1
+        log(f"  sheet {number}/{len(batches)}: {len(seen)} of {len(batch)} described")
+    folder = root / "descriptions"
+    folder.mkdir(parents=True, exist_ok=True)
+    for pack, data in sorted(out.items()):
+        if not data.get("assets") and not data.get("tiles"):
+            continue
+        data = {
+            "pack": pack,
+            **{k: dict(sorted(v.items())) for k, v in data.items() if k != "pack"},
+        }
+        (folder / f"{pack}.json").write_text(json.dumps(data, indent=1) + "\n", encoding="utf-8")
+    rebuild_index(root)
+    return counts

spriteforge/library/looks.py

@@ -0,0 +1,154 @@
+"""What a library image looks like, measured from its pixels (free; no model sees it).
+
+`measure` names the main colours and gives brightness (mean Rec. 709 luma of the drawn
+pixels, 0-1) and detail (the spread between the 10th and 90th percentile of that luma). The
+library descriptions carry it for every asset, the Art Director's list shows it, and the art
+step compares library picks with the colours a design names (`colour_gap`).
+"""
+
+import colorsys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+from pydantic import BaseModel
+
+LUMA = np.array([0.2126, 0.7152, 0.0722])
+FLAT = 0.03  # detail under this: one flat colour (e.g. a wall top with no bricks)
+
+
+class Colour(BaseModel):
+    name: str
+    hex: str
+    share: float  # of the drawn pixels
+
+
+class Look(BaseModel):
+    colours: list[Colour]  # main colours, largest first
+    brightness: float
+    detail: float
+    fill: float  # drawn share of the image
+    mean: str  # mean colour of the drawn pixels
+    text: str  # "tan and brown; mid (0.49); low-contrast detail"
+
+
+def hex_of(rgb) -> str:
+    return "#" + "".join(f"{int(np.rint(c)):02X}" for c in rgb[:3])
+
+
+def rgb_of(hex_code: str) -> tuple[int, int, int]:
+    return tuple(int(hex_code[i : i + 2], 16) for i in (1, 3, 5))
+
+
+def colour_name(rgb) -> str:
+    """A plain colour word for an RGB colour: 'tan', 'dark grey', 'grey-teal', 'olive' ..."""
+    h, s, v = colorsys.rgb_to_hsv(*(c / 255 for c in rgb[:3]))
+    if v < 0.13:
+        return "black"
+    if s < 0.13 or (s < 0.2 and v < 0.3):
+        return (
+            "dark grey" if v < 0.4 else "grey" if v < 0.68 else "light grey" if v < 0.9 else "white"
+        )
+    deg = h * 360
+    if deg < 15 or deg >= 345:
+        base = "red"
+    elif deg < 42:
+        base = "tan" if s < 0.45 and v >= 0.45 else "brown" if v < 0.62 else "orange"
+    elif deg < 70:
+        base = "olive" if v < 0.55 else "cream" if s < 0.4 else "yellow"
+    elif deg < 160:
+        base = "green"
+    elif deg < 195:
+        base = "cyan" if v > 0.75 and s > 0.45 else "teal"
+    elif deg < 255:
+        base = "blue"
+    elif deg < 290:
+        base = "purple"
+    else:
+        base = "pink" if v > 0.75 and s < 0.55 else "magenta"
+    earthy = base in {"tan", "brown", "olive", "cream"}
+    if s < 0.3 and not earthy:
+        base = f"grey-{base}"
+    if v < 0.38 and base not in {"brown", "olive"}:
+        return f"dark {base}"
+    if v > 0.88 and s < 0.5 and not earthy:
+        return f"light {base}"
+    return base
+
+
+def brightness_word(value: float) -> str:
+    for limit, word in ((0.2, "very dark"), (0.38, "dark"), (0.6, "mid"), (0.8, "light")):
+        if value < limit:
+            return word
+    return "very light"
+
+
+def detail_word(value: float) -> str:
+    if value < FLAT:
+        return "flat, no detail"
+    return "low-contrast detail" if value < 0.12 else "high-contrast detail"
+
+
+def measure(image: Image.Image) -> Look:
+    a = np.asarray(image.convert("RGBA"))
+    drawn = a[..., 3] > 127
+    rgb = a[drawn][:, :3]
+    if not len(rgb):
+        return Look(colours=[], brightness=0, detail=0, fill=0, mean="#000000", text="empty")
+    luma = rgb.astype(float) @ LUMA / 255
+    colours, counts = np.unique(rgb, axis=0, return_counts=True)
+    groups: dict[str, list] = {}
+    for colour, count in zip(colours, counts, strict=True):
+        groups.setdefault(colour_name(colour), []).append((colour.astype(float), int(count)))
+    total = int(counts.sum())
+    named = []
+    for name, items in groups.items():
+        n = sum(k for _, k in items)
+        mean = sum(c * k for c, k in items) / n
+        named.append(Colour(name=name, hex=hex_of(mean), share=round(n / total, 3)))
+    named.sort(key=lambda c: (-c.share, c.name))
+    main = [c for c in named if c.share >= 0.08][:4] or named[:1]
+    words = [c.name for c in main]
+    listed = ", ".join(words[:-1]) + " and " + words[-1] if len(words) > 1 else words[0]
+    brightness = round(float(luma.mean()), 3)
+    detail = round(float(np.percentile(luma, 90) - np.percentile(luma, 10)), 3)
+    return Look(
+        colours=main,
+        brightness=brightness,
+        detail=detail,
+        fill=round(float(drawn.mean()), 3),
+        mean=hex_of(rgb.astype(float).mean(axis=0)),
+        text=f"{listed}; {brightness_word(brightness)} ({brightness:.2f}); {detail_word(detail)}",
+    )
+
+
+def lab(hex_code: str) -> np.ndarray:
+    """CIELAB (D65) of an sRGB colour."""
+    rgb = np.array(rgb_of(hex_code)) / 255
+    linear = np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
+    xyz = (
+        np.array([[0.4124, 0.3576, 0.1805], [0.2126, 0.7152, 0.0722], [0.0193, 0.1192, 0.9505]])
+        @ linear
+        / np.array([0.95047, 1.0, 1.08883])
+    )
+    f = np.where(xyz > (6 / 29) ** 3, np.cbrt(xyz), xyz / (3 * (6 / 29) ** 2) + 4 / 29)
+    return np.array([116 * f[1] - 16, 500 * (f[0] - f[1]), 200 * (f[1] - f[2])])
+
+
+def colour_gap(a: str, b: str) -> float:
+    """How far apart two colours look (CIE76 delta E; about 25 and up: clearly different)."""
+    return float(np.linalg.norm(lab(a) - lab(b)))
+
+
+def asset_image(asset: dict, root: Path) -> Image.Image:
+    """What an asset shows: its first drawn frame for an animation sheet, else the image."""
+    image = Image.open(root / asset["file"]).convert("RGBA")
+    w, h = asset["cell"]
+    if asset.get("frames", 1) <= 1 or (w, h) == image.size:
+        return image
+    for y in range(0, image.height - h + 1, h):
+        for x in range(0, image.width - w + 1, w):
+            frame = image.crop((x, y, x + w, y + h))
+            if frame.getchannel("A").getbbox():
+                return frame
+    return image.crop((0, 0, w, h))

spriteforge/library/models.py

@@ -0,0 +1,79 @@
+"""Asset library records: every third-party file carries its pack's source and license."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Licenses that allow shipping the art inside a generated game without extra steps.
+SHIPPABLE = {"CC0", "CC0-1.0", "PUBLIC-DOMAIN", "OWN"}
+# Free-to-use custom licenses: fine inside a built game, but the raw files may not be
+# redistributed (kept out of git via `redistributable: false`).
+FREE_USE = {"FREE-USE"}
+# Licenses that allow shipping only with attribution (credits file is written into the build).
+ATTRIBUTION = {"CC-BY-3.0", "CC-BY-4.0", "OGA-BY-3.0", "MIT"}
+
+Category = Literal[
+    "character",
+    "enemy",
+    "tileset",
+    "prop",
+    "item",
+    "equipment",
+    "ui",
+    "effect",
+    "background",
+    "other",
+]
+
+
+class Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class AssetEntry(Strict):
+    id: str  # "<pack>/<slug>"
+    file: str  # path relative to the library root
+    category: Category
+    subcategory: str = ""
+    name: str
+    tags: list[str] = Field(default_factory=list)
+    size: tuple[int, int]
+    # Grid cell when the file is a sheet; equals size for a single sprite.
+    cell: tuple[int, int]
+    frames: int = 1
+    colors: int
+    opaque_bbox: tuple[int, int, int, int] | None
+    transparent_background: bool
+    sha256: str
+
+
+class Pack(Strict):
+    id: str = Field(pattern=r"^[a-z0-9][a-z0-9-]*$")
+    title: str
+    author: str = "unknown"
+    source_url: str = ""
+    license: str = "UNKNOWN"
+    license_url: str = ""
+    license_verified: bool = False
+    notes: str = ""
+    original_archive: str = ""
+    # False: raw files may not be shared (public repo, zip of the library); builds still may.
+    redistributable: bool = True
+    # False: the license forbids AI use (e.g. "no AI training"); never send to Muse as a
+    # reference or training input. Builds may still include the art.
+    ai_allowed: bool = True
+    # Which way side-facing sprites in this pack look. Kits expect right-facing art and flip
+    # it when moving left, so "left" packs are mirrored when they are adapted into a slot.
+    faces: Literal["right", "left"] = "right"
+    assets: list[AssetEntry] = Field(default_factory=list)
+
+    @property
+    def usage(self) -> Literal["ship", "ship-with-credit", "reference-only"]:
+        """What a build may do with this pack. Unverified packs are never shipped."""
+        if not self.license_verified:
+            return "reference-only"
+        if self.license.upper() in SHIPPABLE | FREE_USE:
+            return "ship"
+        if self.license.upper() in ATTRIBUTION:
+            return "ship-with-credit"
+        return "reference-only"