Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

feat(capabilities): sprite-gen capabilities prints every verb and argument read off the CLI's parser, the providers each verb may call and be billed by, and the address and login variables, as one JSON line

Soohong Kim7c2120b63c23
diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.py
index 3f1c66b..0b37dc7 100644
--- a/sprite_gen/_modules.py
+++ b/sprite_gen/_modules.py
@@ -9,6 +9,7 @@ MODULE_DOMAIN = {
'sound': 'audio',
'guide': 'workflow',
'preferences': 'workflow',
+ 'capabilities': 'workflow',
'runio': 'spec',
'assets': 'spec',
'tile': 'background',
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index e47749a..a651353 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -38,7 +38,7 @@ from sprite_gen.effects import breathe, recolor, shadow
from sprite_gen.scene import render, inspect_scene
from sprite_gen.serve import serve_compose, serve_curation
from sprite_gen.spec import migrate_breathe, migrate_request
-from sprite_gen.workflow import guide, preferences
+from sprite_gen.workflow import capabilities, guide, preferences
from sprite_gen.util.console import utf8_streams
@@ -227,6 +227,12 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
"scene-inspect": ("Measure scene loops, viewport clipping and repeated joins.", inspect_scene.add_arguments, inspect_scene.run),
"workflow": ("Resolve image/sprite choices, check access and guide the next conversation step.", guide.add_arguments, guide.run),
"defaults": ("Show, explicitly save or clear the defaults for each user workflow.", preferences.add_arguments, preferences.run),
+ # Read off this table and the parser it builds (docs/capabilities.md): a verb added here is listed there.
+ "capabilities": (
+ "Print what this engine can do as one JSON line: every verb and its arguments, read off this CLI's parser, the providers each verb may call and be billed by, and the provider address and login variables.",
+ capabilities.add_arguments,
+ capabilities.run,
+ ),
"prepare": ("Prepare a sprite-gen component-row run.", prepare.add_arguments, prepare.run),
"extract": ("Extract component-row sprite strips into clean RGBA frames.", _add_extract, extract.run),
"compose-atlas": (
diff --git a/sprite_gen/workflow/capabilities.py b/sprite_gen/workflow/capabilities.py
new file mode 100644
index 0000000..9e47d19
--- /dev/null
+++ b/sprite_gen/workflow/capabilities.py
@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: Apache-2.0
+"""What this engine can do, for a machine to read (docs/capabilities.md).
+
+Every verb and every argument is read off the CLI's own parser (`cli.COMMANDS` and `cli._build_parser`), so a verb
+or flag added there is listed with nothing else written. The one fact the parser does not hold is which providers
+a verb may call and be billed by (`PROVIDER_CALLS`). Beside the verbs: where each provider is by default and the
+variables that move it (`gen.address`), its API key's variable, and the variable that turns subscription logins
+off (`gen.base.logins_on`). Printed as one compact JSON line, so an agent reads it once instead of every `--help`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from importlib.metadata import PackageNotFoundError, version as package_version
+from pathlib import PurePath
+from typing import Any
+
+from sprite_gen.audio import provider as sound_provider
+from sprite_gen.gen import address, anthropic_api, openai_provider, xai
+from sprite_gen.gen.base import LOGINS_ENV
+from sprite_gen.util.console import utf8_streams
+
+KIND = "sprite-gen-capabilities"
+
+# The providers each verb may call over HTTP (`address.PROVIDERS`); a verb not named calls none. `gen`, `gen-set`
+# and `logo` reach OpenAI by `--provider openai` and xAI by `--provider grok` (codex runs on its own login,
+# `base.logins_on`); `curation` reaches xAI by its reroll and in-between buttons (codex or grok); `video-set` makes
+# each clip with `video` and checks a side view's facing on Grok.
+PROVIDER_CALLS: dict[str, tuple[str, ...]] = {
+ "gen": ("openai", "xai"),
+ "gen-set": ("openai", "xai"),
+ "logo": ("openai", "xai"),
+ "pixel-draw": ("anthropic",),
+ "sound": ("elevenlabs",),
+ "curation": ("xai",),
+ "video": ("xai",),
+ "video-extend": ("xai",),
+ "video-edit": ("xai",),
+ "video-resume": ("xai",),
+ "video-set": ("xai",),
+}
+# Verbs that call a provider and buy nothing: `video-resume` polls and downloads a clip an earlier run bought.
+NO_PURCHASE = frozenset({"video-resume"})
+KEY_ENVS = {"openai": openai_provider.AUTH_ENV, "xai": xai.AUTH_ENV, "anthropic": anthropic_api.AUTH_ENV,
+ "elevenlabs": sound_provider.AUTH_ENV}
+# Argument types by name; any other is its parsing function's name without `_` and `parse_` (`_parse_grid`: grid).
+TYPES = {str: None, int: "int", float: "float"}
+
+
+def _version() -> str:
+ try:
+ return package_version("sprite-gen")
+ except PackageNotFoundError: # pragma: no cover - bare checkout
+ return "unknown"
+
+
+def _json(value: Any) -> Any:
+ if isinstance(value, PurePath):
+ return value.as_posix()
+ if isinstance(value, (list, tuple)):
+ return [_json(item) for item in value]
+ if value is None or isinstance(value, (str, int, float, bool)):
+ return value
+ return str(value)
+
+
+def _type(action: argparse.Action) -> str | None:
+ if action.nargs == 0:
+ return "flag"
+ if action.type is None or action.type in TYPES:
+ return TYPES.get(action.type)
+ if isinstance(action.type, type) and issubclass(action.type, PurePath):
+ return "path"
+ name = getattr(action.type, "__name__", type(action.type).__name__).lstrip("_")
+ return name.removeprefix("parse_")
+
+
+def _spelled(action: argparse.Action) -> list[str]:
+ """Its spellings, the first long one first: `--out`, then `-o`."""
+ return sorted(action.option_strings, key=lambda s: not s.startswith("--")) or [action.dest]
+
+
+def _argument(action: argparse.Action) -> dict[str, Any]:
+ name, *aliases = _spelled(action)
+ entry: dict[str, Any] = {"name": name}
+ if aliases:
+ entry["aliases"] = aliases
+ if not action.option_strings:
+ entry["positional"] = True
+ kind = _type(action)
+ if kind:
+ entry["type"] = kind
+ if action.nargs not in (None, 0):
+ entry["nargs"] = action.nargs
+ if isinstance(action, argparse._AppendAction):
+ entry["repeat"] = True
+ # A flag is off unless given; say its default only when it is not.
+ if action.default not in (None, argparse.SUPPRESS) and not (action.nargs == 0 and action.default is False):
+ entry["default"] = _json(action.default)
+ if action.required and action.option_strings:
+ entry["required"] = True
+ if action.choices is not None:
+ entry["choices"] = _json(list(action.choices))
+ return entry
+
+
+def _parser(parser: argparse.ArgumentParser) -> dict[str, Any]:
+ """Its arguments as `--help` shows them, the groups of which at most one is given, and its own sub-verbs."""
+ shown = [a for a in parser._actions if a.help != argparse.SUPPRESS]
+ entry: dict[str, Any] = {"args": [_argument(a) for a in shown
+ if not isinstance(a, (argparse._HelpAction, argparse._SubParsersAction))]}
+ exclusive = [{"one_of": [_spelled(a)[0] for a in group._group_actions],
+ **({"required": True} if group.required else {})} for group in parser._mutually_exclusive_groups]
+ if exclusive:
+ entry["exclusive"] = exclusive
+ for action in shown:
+ if isinstance(action, argparse._SubParsersAction):
+ entry["commands"] = {name: {**({"description": sub.description} if sub.description else {}), **_parser(sub)}
+ for name, sub in action.choices.items()}
+ return entry
+
+
+def document() -> dict[str, Any]:
+ """The whole document: every verb of `cli.COMMANDS`, in its order, from the parser the CLI runs."""
+ from sprite_gen import cli # the CLI imports this module to register the verb
+
+ parsed = _parser(cli._build_parser())["commands"]
+ domains = {verb: domain for domain, verbs in cli.command_domains().items() for verb in verbs}
+ old_names: dict[str, list[str]] = {}
+ for old, (new, _run) in cli.VERB_ALIASES.items():
+ old_names.setdefault(new, []).append(old)
+ verbs: dict[str, Any] = {}
+ for name, (description, _add_arguments, _run) in cli.COMMANDS.items():
+ providers = PROVIDER_CALLS.get(name, ())
+ entry: dict[str, Any] = {"domain": domains[name], "description": description}
+ if providers:
+ entry["providers"] = list(providers)
+ entry["paid"] = bool(providers) and name not in NO_PURCHASE
+ if name in old_names:
+ entry["old_names"] = old_names[name]
+ verbs[name] = {**entry, **parsed[name]}
+ return {
+ "kind": KIND,
+ "version": _version(),
+ "providers": {name: {"base_url_env": provider.env, "base_url": provider.default, "key_env": KEY_ENVS[name]}
+ for name, provider in address.PROVIDERS.items()},
+ "logins_env": LOGINS_ENV,
+ "verbs": verbs,
+ }
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+ """No arguments: the document is the whole engine."""
+
+
+def run(**_kwargs: object) -> int:
+ utf8_streams()
+ print(json.dumps(document(), ensure_ascii=False, separators=(",", ":")))
+ return 0
diff --git a/tests/test_cli_kwargs.py b/tests/test_cli_kwargs.py
index aad1c7f..f349f68 100644
--- a/tests/test_cli_kwargs.py
+++ b/tests/test_cli_kwargs.py
@@ -117,7 +117,8 @@ def test_a_verb_called_without_a_required_flag_names_it(module, run, required):
def test_no_function_reads_a_parsers_actions_but_these():
"""`parser._actions` read anywhere else in the engine is a second reading of keyword arguments,
the copy this file exists to keep out. `extract._nondefault_args` asks another question of its
- parser: which flags a run set off their defaults, for the manifest."""
+ parser: which flags a run set off their defaults, for the manifest. `capabilities._parser` asks
+ what each verb's parser declares, for a machine to read (docs/capabilities.md)."""
readers = set()
for path in sorted((ROOT / "sprite_gen").rglob("*.py")):
for function in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
@@ -125,4 +126,5 @@ def test_no_function_reads_a_parsers_actions_but_these():
isinstance(node, ast.Attribute) and node.attr == "_actions" for node in ast.walk(function)):
readers.add((path.relative_to(ROOT).as_posix(), function.name))
assert readers == {("sprite_gen/util/cli_kwargs.py", "namespace_from_kwargs"),
- ("sprite_gen/frames/extract.py", "_nondefault_args")}
+ ("sprite_gen/frames/extract.py", "_nondefault_args"),
+ ("sprite_gen/workflow/capabilities.py", "_parser")}
diff --git a/tests/workflow/test_capabilities.py b/tests/workflow/test_capabilities.py
new file mode 100644
index 0000000..ec3fd5a
--- /dev/null
+++ b/tests/workflow/test_capabilities.py
@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sprite-gen capabilities` (docs/capabilities.md): every verb and argument as the parser declares them, read off
+the parser itself, so a verb or flag added to the CLI is in it with nothing else written; which providers each verb
+may call and be billed by; the provider address and login variables. One compact JSON line, a fraction of every
+`--help` together."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from sprite_gen import cli
+from sprite_gen.gen import address
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def _document() -> dict:
+ from sprite_gen.workflow import capabilities
+ return capabilities.document()
+
+
+def _subparsers(parser: argparse.ArgumentParser) -> dict[str, argparse.ArgumentParser]:
+ return next(a for a in parser._actions if isinstance(a, argparse._SubParsersAction)).choices
+
+
+def _visible(parser: argparse.ArgumentParser) -> list[argparse.Action]:
+ return [a for a in parser._actions if a.help != argparse.SUPPRESS
+ and not isinstance(a, (argparse._HelpAction, argparse._SubParsersAction))]
+
+
+def _printed(cmd: list[str]) -> str:
+ proc = subprocess.run([sys.executable, "-m", "sprite_gen.cli", *cmd], capture_output=True, encoding="utf-8",
+ cwd=ROOT, env={**os.environ, "PYTHON_COLORS": "0", "PYTHONPATH": str(ROOT)})
+ assert proc.returncode == 0, proc.stderr
+ return proc.stdout
+
+
+def test_every_verb_and_old_name_is_listed_once() -> None:
+ verbs = _document()["verbs"]
+ assert list(verbs) == list(cli.COMMANDS)
+ old = {name: verb for verb, entry in verbs.items() for name in entry.get("old_names", [])}
+ assert old == {name: new for name, (new, _run) in cli.VERB_ALIASES.items()}
+ assert len(verbs) + len(old) == len(_subparsers(cli._build_parser()))
+
+
+def test_each_verb_is_its_parser_argument_for_argument() -> None:
+ """Name, other spellings, type, how many values, default, required and choices: what the parser holds."""
+ verbs = _document()["verbs"]
+ for name, sub in _subparsers(cli._build_parser()).items():
+ if name in cli.VERB_ALIASES:
+ continue
+ entry = verbs[name]
+ assert entry["description"] == sub.description
+ assert entry["domain"] == next(d for d, vs in cli.command_domains().items() if name in vs)
+ args = entry["args"]
+ actions = _visible(sub)
+ assert len(args) == len(actions), name
+ for arg, action in zip(args, actions):
+ spelled = action.option_strings or [action.dest]
+ assert [arg["name"], *arg.get("aliases", [])] == [*sorted(spelled, key=lambda s: not s.startswith("--"))]
+ assert arg.get("positional", False) is (not action.option_strings)
+ assert arg.get("required", False) is bool(action.required and action.option_strings)
+ assert arg.get("choices") == (list(action.choices) if action.choices is not None else None)
+ assert arg.get("nargs") == (action.nargs if action.nargs not in (None, 0) else None)
+ assert arg.get("repeat", False) is isinstance(action, argparse._AppendAction)
+
+
+def test_every_flag_a_verbs_help_prints_is_listed(monkeypatch) -> None:
+ """Read off another source than the parser's actions: the help text a person reads (wide, so no flag wraps)."""
+ monkeypatch.setenv("COLUMNS", "1000")
+ verbs = _document()["verbs"]
+ for name, sub in _subparsers(cli._build_parser()).items():
+ entry = verbs[cli.VERB_ALIASES[name][0] if name in cli.VERB_ALIASES else name]
+ listed = {spelled for arg in entry["args"] for spelled in (arg["name"], *arg.get("aliases", []))}
+ # An option's line opens with its spellings, then two spaces and its help (which may name other verbs' flags).
+ invocations = [re.split(r"\s{2,}", line.strip())[0] for line in sub.format_help().splitlines()
+ if line.startswith(" -")]
+ printed = {flag for line in invocations for flag in re.findall(r"--[a-z][\w-]*", line)} - {"--help"}
+ assert printed == {s for s in listed if s.startswith("--")}, name
+
+
+def test_types_defaults_and_flags_are_written_as_json() -> None:
+ gen = {arg["name"]: arg for arg in _document()["verbs"]["gen"]["args"]}
+ assert gen["--out"]["type"] == "path" and gen["--out"]["required"] is True
+ assert gen["--provider"]["choices"] == ["codex", "grok", "openai"]
+ slicing = {arg["name"]: arg for arg in _document()["verbs"]["slice-sheet"]["args"]}
+ assert slicing["--grid"] == {"name": "--grid", "type": "grid", "default": [3, 2]}
+ assert slicing["--cell-width"] == {"name": "--cell-width", "type": "int", "default": 512}
+ inputs = {arg["name"]: arg for arg in _document()["verbs"]["compose-gif"]["args"]}["inputs"]
+ assert inputs == {"name": "inputs", "positional": True, "type": "path", "nargs": "*"}
+ sound = {arg["name"]: arg for arg in _document()["verbs"]["sound"]["args"]}
+ assert sound["--loop"] == {"name": "--loop", "aliases": ["--no-loop"], "type": "flag"}
+ assert _document()["verbs"]["sound"]["exclusive"] == [{"one_of": ["--prompt", "--prompt-file"], "required": True}]
+ rife = _document()["verbs"]["rife"]
+ assert rife["args"] == [] and list(rife["commands"]) == ["install"]
+ assert {arg["name"] for arg in rife["commands"]["install"]["args"]} == {"--dir", "--zip", "--force", "--no-check",
+ "--backend"}
+
+
+def test_a_verb_or_flag_added_to_the_cli_is_listed_with_nothing_else_written(monkeypatch) -> None:
+ def add(parser: argparse.ArgumentParser) -> None:
+ parser.add_argument("--depth", type=int, default=3, choices=(1, 2, 3))
+ parser.add_argument("--note", required=True)
+
+ commands = {**cli.COMMANDS, "probe-verb": ("A verb this test adds.", add, lambda **_: 0)}
+ monkeypatch.setattr(cli, "COMMANDS", commands)
+ monkeypatch.setitem(sys.modules["sprite_gen._modules"].MODULE_DOMAIN, "test_capabilities", "workflow")
+ entry = _document()["verbs"]["probe-verb"]
+ assert entry["description"] == "A verb this test adds."
+ assert entry["args"] == [{"name": "--depth", "type": "int", "default": 3, "choices": [1, 2, 3]},
+ {"name": "--note", "required": True}]
+ assert "providers" not in entry and entry["paid"] is False
+
+
+def test_the_providers_of_each_verb_are_known_providers_of_real_verbs() -> None:
+ from sprite_gen.workflow import capabilities
+ assert set(capabilities.PROVIDER_CALLS) <= set(cli.COMMANDS)
+ assert {p for providers in capabilities.PROVIDER_CALLS.values() for p in providers} <= set(address.PROVIDERS)
+ assert capabilities.NO_PURCHASE <= set(capabilities.PROVIDER_CALLS)
+
+
+def test_what_each_paid_verb_calls() -> None:
+ verbs = _document()["verbs"]
+ paid = {name: entry["providers"] for name, entry in verbs.items() if entry["paid"]}
+ assert paid == {
+ "gen": ["openai", "xai"], "gen-set": ["openai", "xai"], "logo": ["openai", "xai"],
+ "pixel-draw": ["anthropic"], "sound": ["elevenlabs"], "curation": ["xai"],
+ "video": ["xai"], "video-extend": ["xai"], "video-edit": ["xai"], "video-set": ["xai"],
+ }
+ assert verbs["video-resume"]["providers"] == ["xai"] and verbs["video-resume"]["paid"] is False
+ assert "providers" not in verbs["video-loop"] and verbs["video-loop"]["paid"] is False
+
+
+def test_the_provider_section_is_the_address_registry_and_the_key_names() -> None:
+ document = _document()
+ assert document["kind"] == "sprite-gen-capabilities"
+ assert document["logins_env"] == "SPRITE_GEN_LOGINS"
+ assert document["providers"] == {
+ "openai": {"base_url_env": "SPRITE_GEN_OPENAI_BASE_URL", "base_url": "https://api.openai.com/v1",
+ "key_env": "OPENAI_API_KEY"},
+ "xai": {"base_url_env": "SPRITE_GEN_XAI_BASE_URL", "base_url": "https://api.x.ai/v1", "key_env": "XAI_API_KEY"},
+ "anthropic": {"base_url_env": "SPRITE_GEN_ANTHROPIC_BASE_URL", "base_url": "https://api.anthropic.com/v1",
+ "key_env": "ANTHROPIC_API_KEY"},
+ "elevenlabs": {"base_url_env": "SPRITE_GEN_ELEVENLABS_BASE_URL", "base_url": "https://api.elevenlabs.io/v1",
+ "key_env": "ELEVENLABS_API_KEY"},
+ }
+
+
+def test_the_document_ignores_the_address_variables(monkeypatch) -> None:
+ """It says where each provider is by default; what this process has set is not part of what the engine can do."""
+ plain = _document()
+ monkeypatch.setenv("SPRITE_GEN_XAI_BASE_URL", "http://127.0.0.1:9/xai")
+ assert _document() == plain
+
+
+def test_the_verb_prints_one_compact_json_line_a_fraction_of_every_help() -> None:
+ printed = _printed(["capabilities"])
+ assert printed.count("\n") == 1 and printed.endswith("\n")
+ assert json.loads(printed)["verbs"] == json.loads(json.dumps(_document()))["verbs"]
+ parser = cli._build_parser()
+ helps = len(parser.format_help().encode()) + sum(len(sub.format_help().encode())
+ for sub in _subparsers(parser).values())
+ assert len(printed.encode()) * 2 < helps