spriteforge 0.1.1__py3-none-any.whl

spriteforge/memory/okf/catalog.py

@@ -0,0 +1,331 @@
+"""Mirror asset packs, tile sets and actors into the OKF corpus under `catalog/`.
+
+Agents navigate knowledge through memory_index / memory_search / memory_show, so the art
+inventory must live there too, not only in assets/library/index.json. Everything here is
+derived from files on disk (pack.json, library/tilesets/*.json); re-running the sync rewrites
+only entries whose text changed and deprecates entries whose source disappeared (e.g. the kit
+and skin entries from before games were written from the prompt).
+"""
+
+from spriteforge.game.actors import ANIM_SOURCES, load_actors
+from spriteforge.game.art import actor_sheet, reference_assets, whole_objects
+from spriteforge.game.tilesets import load_tilesets
+from spriteforge.library.store import library_root, load_packs, search, tile_descriptions
+
+from .models import Entry, Metadata
+from .store import KnowledgeStore
+
+SOURCE = {"resource": "spriteforge catalog sync", "author": "spriteforge/catalog"}
+USAGE_TEXT = {
+    "ship": "may be used in builds as-is",
+    "ship-with-credit": "may be used in builds with a credits line",
+    "reference-only": "reference only: never put into a build",
+}
+CAMERA = {"side": "side-view", "topdown": "top-down"}
+
+
+def entry(ident: str, type_: str, title: str, description: str, tags, body: str, source: str):
+    return Entry(
+        id=ident,
+        metadata=Metadata(
+            type=type_,
+            title=title,
+            description=description,
+            tags=sorted({t.lower() for t in tags if t}),
+            sources=[{**SOURCE, "id": source}],
+        ),
+        body=body.strip() + "\n",
+    )
+
+
+def guide_entry() -> Entry:
+    body = """
+# How a game is made
+Muse Spark writes every game from the human's request; there are no pre-built game templates.
+1. The Game Designer writes a design doc: rules, every entity the player sees, progression,
+   difficulty over time, win/lose, and *checks* (events the code must emit) - G2 gate.
+2. The Art Director picks art per entity: the local library first (actors, whole objects,
+   tile-set tiles, parallax backdrops), Muse Image for anything the library lacks.
+3. The Programmer writes the Phaser 3 code against the SpriteForge SDK; the harness checks it,
+   playtests the whole session with the game's own bot and sends failures back - G4 gate.
+
+# What the library offers
+Start at `catalog/library` (everything at a glance), then `catalog/packs/<pack>` (every asset
+by category), `catalog/actors/<actor>` (animations, camera) and `catalog/tilesets/<id>`.
+
+# License rules (enforced in code, repeated here for planning)
+* Only packs whose usage is `ship` or `ship-with-credit` may appear in a build.
+* `ai_allowed: false` packs must never be sent to Muse as references or edit inputs; their art
+  may still be used in a build as-is.
+* `redistributable: false` packs stay on this machine (git-ignored); builds may include them.
+* Side-view art faces right in a game; packs marked `faces: left` are mirrored.
+* Library first: if the library has the same kind of creature or object for the game's camera,
+  it is used; otherwise Muse Image draws it from a concrete prompt with an AI-allowed style
+  reference. Greybox appears only when the per-build image cap is reached or Muse fails.
+"""
+    return entry(
+        "catalog/guide",
+        "Catalog Guide",
+        "How games are made and how agents use the art library",
+        "Design -> art (library first, else Muse) -> code; license rules.",
+        ["catalog", "guide", "license", "asset", "actor", "tileset", "muse"],
+        body,
+        "guide",
+    )
+
+
+def tileset_entry(ts: dict) -> Entry:
+    tiles = "".join(f"| `{ts['id']}/{n}` | {t['what']} |\n" for n, t in ts["tiles"].items())
+    variants = "".join(
+        f"* `{name}`: for worlds described with {', '.join(v['words']) or '(default)'}\n"
+        for name, v in ts["variants"].items()
+    )
+    body = f"""
+# Summary
+{ts["summary"]}
+
+Camera: **{ts["camera"]}**, {ts["tile_size"]} px tiles. Pack: [{ts["pack"]}](../packs/{ts["pack"]}.md).
+Fits worlds described with: {", ".join(ts["keywords"])}.
+{"Has a parallax backdrop (ArtPlan source=backdrop, asset=" + ts["id"] + ")." if ts.get("backdrop") else ""}
+
+# Variants
+{variants}
+# Tiles (ArtPlan source=tile)
+| Asset | What |
+|---|---|
+{tiles}
+"""
+    return entry(
+        f"catalog/tilesets/{ts['id']}",
+        "Tile Set",
+        ts["id"].replace("-", " ").title(),
+        f"{ts['camera']} {ts['tile_size']} px tiles from {ts['pack']}: {ts['summary']}",
+        ["tileset", "tiles", ts["camera"], *ts["keywords"], *ts["variants"], *ts["tiles"]],
+        body,
+        f"src/spriteforge/library/tilesets/{ts['id']}.json",
+    )
+
+
+def pack_entry(pack) -> Entry:
+    counts: dict[str, int] = {}
+    for a in pack.assets:
+        counts[a.category] = counts.get(a.category, 0) + 1
+    tags = sorted({t for a in pack.assets for t in a.tags})
+    grid = sorted({f"{a.cell[0]}x{a.cell[1]}" for a in pack.assets if a.frames > 1})
+    body = f"""
+# Summary
+{pack.title} by {pack.author}. {len(pack.assets)} assets:
+{", ".join(f"{n} {c}" for c, n in sorted(counts.items()))}.
+
+# License and handling
+* License: **{pack.license}** ({"verified" if pack.license_verified else "NOT verified"}).
+* Usage: `{pack.usage}`: {USAGE_TEXT[pack.usage]}.
+* AI use: {"allowed" if pack.ai_allowed else "**forbidden**: never send to Muse"}.
+* Redistributable: {"yes" if pack.redistributable else "no (git-ignored, local only)"}.
+* Side-view art faces: {pack.faces}.
+* Source: {pack.source_url or "not recorded"}.
+
+# Notes
+{pack.notes}
+
+# Grids
+Animation/tile cells: {", ".join(grid) or "single images"}. Files live under
+`assets/library/{pack.id}/`.
+
+# Contents
+{pack_contents(pack)}
+"""
+    return entry(
+        f"catalog/packs/{pack.id}",
+        "Asset Pack",
+        pack.title,
+        f"{pack.license} ({pack.usage}{'' if pack.ai_allowed else ', no AI'}): "
+        + ", ".join(f"{n} {c}" for c, n in sorted(counts.items())),
+        ["asset-pack", pack.id, pack.license, pack.usage, *tags[:20]],
+        body,
+        f"assets/library/{pack.id}/pack.json",
+    )
+
+
+def _asset_line(a, notes: dict | None = None) -> str:
+    grid = f"{a.cell[0]}x{a.cell[1]}" + (f" x{a.frames}" if a.frames > 1 else "")
+    note = (notes or {}).get(a.id, {})
+    shows = f": {note['what']}" if note.get("described_by", "measured") != "measured" else ""
+    return f"`{a.id}` {a.name} ({grid}){shows}"
+
+
+def described(note: dict | None) -> str:
+    """' — <what the image shows>; looks <measured>' from `spriteforge library describe`."""
+    if not note or not note.get("described_by"):
+        return ""
+    parts = [note["description"].rstrip(".")] if note["described_by"] != "measured" else []
+    if note.get("look"):
+        parts.append(f"looks {note['look']}")
+    return f" — {'; '.join(parts)}" if parts else ""
+
+
+def pack_contents(pack) -> str:
+    """Every asset by category, so an agent can see that a pack has, say, bonfires or icons."""
+    notes = {a["id"]: a for a in search()}
+    lines = []
+    for cat in sorted({a.category for a in pack.assets}):
+        items = [a for a in pack.assets if a.category == cat]
+        shown = items if len(items) <= 40 else items[:40]
+        more = f" ... and {len(items) - 40} more" if len(items) > 40 else ""
+        lines.append(
+            f"* **{cat}** ({len(items)}): " + "; ".join(_asset_line(a, notes) for a in shown) + more
+        )
+    return "\n".join(lines)
+
+
+def library_entry() -> Entry:
+    """One page an agent reads to know the whole library: packs, actors, objects, tile sets."""
+    packs = {p.id: p for p in load_packs()} if library_root().exists() else {}
+    rows = []
+    for p in packs.values():
+        counts: dict[str, int] = {}
+        for a in p.assets:
+            counts[a.category] = counts.get(a.category, 0) + 1
+        views = sorted({t for a in p.assets for t in a.tags if t in {"top-down", "side-view"}})
+        rows.append(
+            f"| `{p.id}` | {', '.join(views) or 'any'} | "
+            + ", ".join(f"{n} {c}" for c, n in sorted(counts.items()))
+            + f" | {p.usage} | {'yes' if p.ai_allowed else '**no**'} |"
+        )
+    actors = load_actors() if packs else []
+    notes = {a["id"]: a for a in search()} if packs else {}
+    actor_lines = "\n".join(
+        f"* `{a.key}` ({CAMERA[a.side()]} {'hero' if a.category == 'character' else 'enemy'}): "
+        + ", ".join(sorted(a.anims))
+        + described(notes.get(actor_sheet(a)))
+        for a in actors
+    )
+    objects = whole_objects() if packs else {}
+    object_lines = "\n".join(
+        f"* `{i}` {o['category']}: {o['name']} ({o['cell'][0]}x{o['cell'][1]}"
+        + (f", {o['frames']} frames" if o["frames"] > 1 else "")
+        + ("" if o.get("ai_allowed", True) else ", no AI")
+        + ")"
+        + described(notes.get(i))
+        for i, o in sorted(objects.items())
+    )
+    tilesets = load_tilesets() if packs else []
+    tile_notes = tile_descriptions() if packs else {}
+    tile_lines = "\n".join(
+        f"* `{ts['id']}` ({ts['camera']}, {ts['tile_size']} px): "
+        + ", ".join(ts["tiles"])
+        + "".join(
+            f"\n  * `{ts['id']}/{n}` {t['what']}" + described(tile_notes.get(f"{ts['id']}/{n}"))
+            for n, t in ts["tiles"].items()
+        )
+        for ts in tilesets
+    )
+    refs = sorted({a["pack"] for a in reference_assets().values()}) if packs else []
+    body = f"""
+# Packs
+| Pack | Camera | Contents | Usage | AI use |
+| --- | --- | --- | --- | --- |
+{chr(10).join(rows) or "| (no packs installed) | | | | |"}
+
+Details per pack (every asset by category): `catalog/packs/<pack>`.
+
+# Actors (animated characters and enemies; ArtPlan source=actor)
+{actor_lines or "none installed"}
+
+# Tile sets (ArtPlan source=tile / backdrop)
+{tile_lines or "none installed"}
+
+# Whole objects (pickups, props, projectiles; ArtPlan source=object)
+{object_lines or "none installed"}
+
+# Muse style references
+Packs Muse may see as a style example: {", ".join(f"`{r}`" for r in refs) or "none"}.
+Anything the library lacks is drawn by Muse Image (source=muse with a concrete prompt).
+"""
+    return entry(
+        "catalog/library",
+        "Asset Library",
+        "What the local pixel-art library contains",
+        f"{len(packs)} packs, {len(actors)} actors, {len(tilesets)} tile sets, "
+        f"{len(objects)} whole objects",
+        ["catalog", "library", "asset", "pack", "actor", "tileset", "muse", "reference"],
+        body,
+        "assets/library/index.json",
+    )
+
+
+def actor_slug(key: str) -> str:
+    return key.replace("/", "-").replace(" ", "-")
+
+
+def actor_entry(actor, packs: dict) -> Entry:
+    pack = packs.get(actor.pack)
+    camera = CAMERA[actor.side()]
+    anims = ", ".join(f"{a} x{len(f)}" for a, f in sorted(actor.anims.items()))
+    usable = sorted(k for k, sources in ANIM_SOURCES.items() if set(sources) & set(actor.anims))
+    flying = "fly" in actor.anims or "eye" in actor.tokens
+    role = "playable character" if actor.category == "character" else "enemy"
+    body = f"""
+# Summary
+{actor.name.title()} from [{actor.pack}](../packs/{actor.pack}.md); {camera} art,
+{role}{", flies" if flying else ""}. Use it in an ArtPlan as source=actor, asset=`{actor.key}`
+for a {camera} game.
+
+# Animations
+{anims}. Can stand in for animations: {", ".join(usable)}.
+
+# Handling
+Usage `{pack.usage if pack else "unknown"}`; AI use {"allowed" if pack and pack.ai_allowed else "forbidden"};
+faces {actor.faces}. Matched from requests by the words: {", ".join(sorted(actor.tokens))}.
+"""
+    return entry(
+        f"catalog/actors/{actor_slug(actor.key)}",
+        "Actor",
+        f"{actor.name.title()} ({actor.pack})",
+        f"{camera} {'hero' if actor.category == 'character' else 'enemy'}"
+        f"{' (flying)' if flying else ''}: {anims}",
+        ["actor", camera, actor.category, actor.pack, *actor.tokens],
+        body,
+        f"assets/library/{actor.pack}",
+    )
+
+
+def catalog_entries() -> list[Entry]:
+    packs = {p.id: p for p in load_packs()} if library_root().exists() else {}
+    entries = [guide_entry(), library_entry()]
+    entries += [tileset_entry(ts) for ts in load_tilesets()]
+    entries += [pack_entry(p) for p in packs.values()]
+    if packs:
+        entries += [actor_entry(a, packs) for a in load_actors()]
+    return entries
+
+
+def sync_catalog(store: KnowledgeStore) -> dict[str, int]:
+    """Write changed catalog entries; deprecate ones whose source is gone. One git commit."""
+    present, _ = store.scan()
+    current = {e.id: e for e in present if e.id.startswith("catalog/")}
+    wanted = {e.id: e for e in catalog_entries()}
+    changed = [
+        e
+        for e in wanted.values()
+        if e.id not in current
+        or current[e.id].body != e.body
+        or current[e.id].metadata.description != e.metadata.description
+        or current[e.id].metadata.status != "stable"
+    ]
+    gone = []
+    for ident, old in current.items():
+        if ident not in wanted and old.metadata.status != "deprecated":
+            meta = old.metadata.model_copy(update={"status": "deprecated"})
+            gone.append(Entry(id=ident, metadata=meta, body=old.body))
+    if changed or gone:
+        store.write_batch(
+            changed + gone,
+            f"Catalog sync: {len(changed)} updated, {len(gone)} deprecated "
+            f"({len(wanted)} packs/tile sets/actors)",
+            actor="spriteforge/catalog",
+        )
+    return {"total": len(wanted), "updated": len(changed), "deprecated": len(gone)}
+
+
+__all__ = ["catalog_entries", "sync_catalog"]

spriteforge/memory/okf/codec.py

@@ -0,0 +1,63 @@
+import re
+from pathlib import PurePosixPath
+
+import yaml
+
+from spriteforge.core.security import redact
+
+from .models import Entry, Metadata
+
+
+class UnsafeKnowledge(ValueError):
+    pass
+
+
+def ensure_no_secrets(text: str) -> None:
+    assignment = r"(?i)(?:api[_-]?key|access[_-]?token|password|secret)\s*[:=]\s*[\"']?[^\s\"'`]+"
+    if redact(text) != text or re.search(assignment, text) or "-----BEGIN PRIVATE KEY" in text:
+        raise UnsafeKnowledge("Credential-like content rejected; no knowledge was persisted")
+
+
+def check_id(ident: str) -> str:
+    path = PurePosixPath(ident)
+    if (
+        not ident
+        or "\\" in ident
+        or ":" in ident
+        or path.is_absolute()
+        or any(p in {".", ".."} or p.startswith(".") for p in path.parts)
+        or str(path) != ident
+        or path.name in {"index", "log"}
+        or ident.endswith(".md")
+    ):
+        raise ValueError("Concept ID must be a safe relative path without .md or reserved names")
+    ensure_no_secrets(ident)
+    return ident
+
+
+def parse(text: str, ident: str) -> Entry:
+    check_id(ident)
+    ensure_no_secrets(text)
+    text = text.lstrip("\ufeff")
+    match = re.match(r"\A---\r?\n(.*?)\r?\n---(?:\r?\n|\Z)", text, re.DOTALL)
+    if match is None:
+        raise ValueError("Missing YAML frontmatter")
+    data = yaml.safe_load(match[1])
+    if not isinstance(data, dict):
+        raise ValueError("Frontmatter must be a mapping")  # noqa: TRY004 -- serialized YAML format error
+    return Entry(id=ident, metadata=Metadata.model_validate(data), body=text[match.end() :])
+
+
+def serialize(entry: Entry) -> str:
+    check_id(entry.id)
+    metadata = entry.metadata.model_dump(mode="json", by_alias=True, exclude_unset=True)
+    if entry.private:
+        metadata["x-spriteforge-scope"] = "private"
+    result = (
+        "---\n"
+        + yaml.safe_dump(metadata, sort_keys=False, allow_unicode=True)
+        + "---\n"
+        + entry.body
+    )
+    ensure_no_secrets(result)
+    return result

spriteforge/memory/okf/git.py

@@ -0,0 +1,104 @@
+import os
+import shutil
+import subprocess
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+from spriteforge.core.security import redact
+
+
+def git(root: Path, *args: str, index: Path | None = None) -> str:
+    command = [
+        "git",
+        "-c",
+        f"safe.directory={root.as_posix()}",
+        "-c",
+        "user.name=SpriteForge",
+        "-c",
+        "user.email=spriteforge@localhost",
+        "-c",
+        "core.hooksPath=/dev/null",
+        "-C",
+        str(root),
+        *args,
+    ]
+    result = subprocess.run(
+        command,
+        env={**os.environ, **({"GIT_INDEX_FILE": str(index)} if index else {})},
+        check=False,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode:
+        raise RuntimeError(redact(result.stderr.strip()))
+    return result.stdout.strip()
+
+
+def init(root: Path) -> None:
+    root.mkdir(parents=True, exist_ok=True)
+    if (root / ".git").exists():
+        return
+    # Two runs opening a new corpus at once must not both `git init` it (the second fails).
+    with write_lock(root.parent / f".{root.name}.init.lock"):
+        if not (root / ".git").exists():
+            git(root, "init", ".")
+
+
+@contextmanager
+def write_lock(path: Path):
+    with path.open("a+b") as handle:
+        if os.name == "nt":
+            import msvcrt
+
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            if os.name == "nt":
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+            else:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def commit(root: Path, paths: list[str], message: str) -> None:
+    real_index = root / git(root, "rev-parse", "--git-path", "index")
+    with tempfile.TemporaryDirectory(dir=real_index.parent) as directory:
+        index = Path(directory) / "index"
+        if real_index.exists():
+            shutil.copyfile(real_index, index)
+        git(root, "add", "--", *paths, index=index)
+        if git(root, "diff", "--cached", "--name-only", index=index):
+            git(root, "commit", "-m", message, "--only", "--", *paths, index=index)
+        os.replace(index, real_index)
+
+
+@contextmanager
+def rollback_git(root: Path):
+    """Restore the exact index and ref if any part of a write batch fails."""
+    index = root / git(root, "rev-parse", "--git-path", "index")
+    previous_index = index.read_bytes() if index.exists() else None
+    try:
+        head = git(root, "rev-parse", "--verify", "HEAD")
+    except RuntimeError:
+        head = None
+    try:
+        yield
+    except BaseException:
+        if head is None:
+            git(root, "update-ref", "-d", "HEAD")
+        else:
+            git(root, "update-ref", "HEAD", head)
+        if previous_index is None:
+            index.unlink(missing_ok=True)
+        else:
+            index.write_bytes(previous_index)
+        raise

spriteforge/memory/okf/indexes.py

@@ -0,0 +1,50 @@
+from pathlib import PurePosixPath
+
+from .models import Entry
+
+
+def indexes(
+    entries: list[Entry],
+    directories: set[str] | None = None,
+    *,
+    absolute: bool = False,
+    title: str = "SpriteForge knowledge",
+) -> dict[str, str]:
+    """Every directory's index.md. `absolute`: links are bundle-relative from the root
+    (`/entities/hero.md`), as OKF recommends; otherwise relative to the index."""
+    dirs = {"", *(directories or set())}
+    for entry in entries:
+        parent = PurePosixPath(entry.id).parent
+        dirs.update(str(p) if str(p) != "." else "" for p in [parent, *parent.parents])
+    files = {}
+    for directory in sorted(dirs):
+        prefix = directory + "/" if directory else ""
+        lines = ['---\nokf_version: "0.2"\n---\n'] if not directory else []
+        lines.append(f"# {directory or title}\n")
+        for child in sorted(
+            d
+            for d in dirs
+            if d
+            and ("" if str(PurePosixPath(d).parent) == "." else str(PurePosixPath(d).parent))
+            == directory
+        ):
+            name = child.rsplit("/", 1)[-1]
+            target = f"/{child}/index.md" if absolute else f"{name}/index.md"
+            lines.append(f"* [{name}]({target}) - Browse {name} summaries.\n")
+        for entry in sorted(entries, key=lambda e: e.id):
+            if str(PurePosixPath(entry.id).parent) not in {
+                directory,
+                "." if not directory else directory,
+            }:
+                continue
+            # Public indexes never expose private concept titles or descriptions.
+            if entry.private and not directory.startswith("user-prefs"):
+                continue
+            title = entry.title.replace("\n", " ").replace("[", "").replace("]", "")
+            summary = (entry.metadata.description or "Open this concept for details.").replace(
+                "\n", " "
+            )
+            target = f"/{entry.id}.md" if absolute else f"{entry.id.rsplit('/', 1)[-1]}.md"
+            lines.append(f"* [{title}]({target}) - {summary}\n")
+        files[prefix + "index.md"] = "".join(lines)
+    return files

spriteforge/memory/okf/models.py

@@ -0,0 +1,114 @@
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, field_validator
+
+
+class Extensible(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class Generated(Extensible):
+    by: str = Field(min_length=1)
+    at: AwareDatetime | None = None
+
+
+class Verified(Extensible):
+    by: str = Field(min_length=1)
+    at: AwareDatetime
+
+
+class Source(Extensible):
+    resource: str = Field(min_length=1)
+    id: str | None = None
+    title: str | None = None
+    author: str | None = None
+    usage_count: int | None = Field(default=None, ge=0)
+    last_modified: AwareDatetime | None = None
+
+
+class Metadata(Extensible):
+    model_config = ConfigDict(
+        extra="allow", populate_by_name=False, validate_by_name=False, validate_by_alias=True
+    )
+    type: str = Field(min_length=1)
+    title: str | None = None
+    description: str | None = None
+    resource: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    sources: list[Source] = Field(default_factory=list)
+    generated: Generated | None = None
+    verified: list[Verified] = Field(default_factory=list)
+    status: Literal["draft", "stable", "deprecated"] = "stable"
+    stale_after: AwareDatetime | None = None
+    scope: Literal["project", "private"] = Field(default="project", alias="x-spriteforge-scope")
+
+    @field_validator("type")
+    @classmethod
+    def nonblank(cls, value):
+        if not value.strip():
+            raise ValueError("type must not be blank")
+        return value
+
+    @field_validator("verified", mode="before")
+    @classmethod
+    def verifier_mapping(cls, value):
+        return [value] if isinstance(value, dict) else value
+
+    @property
+    def trust_tier(self) -> str:
+        if any(v.by.startswith("human:") for v in self.verified):
+            return "human-reviewed"
+        return "machine-confirmed" if self.verified else "unverified"
+
+    @property
+    def stale(self) -> bool:
+        return self.stale_after is not None and datetime.now(UTC) >= self.stale_after
+
+
+class Entry(BaseModel):
+    id: str
+    metadata: Metadata
+    body: str
+
+    @property
+    def private(self) -> bool:
+        return self.id.split("/")[0] == "user-prefs" or self.metadata.scope == "private"
+
+    @property
+    def title(self) -> str:
+        return self.metadata.title or self.id.rsplit("/", 1)[-1].replace("-", " ")
+
+
+class Snippet(BaseModel):
+    id: str
+    title: str
+    trust_tier: str
+    stale: bool
+    status: str
+    scope: str
+    score: float
+    bootstrap_unreviewed: bool = False
+    text: str
+    tokens: int = 0
+
+
+class ValidationReport(BaseModel):
+    errors: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    external: str = "not installed"
+
+
+class GenreSeed(BaseModel):
+    id: str
+    title: str
+    perspective: str
+    controls: str
+    mechanics: str
+    entities: list[str]
+    palette: str
+    assets: dict[str, int]
+    animations: str
+    pitfalls: list[str]
+    questions: list[str] = Field(min_length=5, max_length=8)
+    extra: dict[str, Any] = Field(default_factory=dict)