spriteboy-model-setup

name	spriteboy-model-setup
description	Verify, install, and diagnose SpriteBoy's pinned local background-removal models. Use for model readiness, BiRefNet setup, RMBG license gates, hash or smoke failures, and local model storage checks.

SpriteBoy model setup

Work from the SpriteBoy checkout. Treat core/models/modelCatalog.ts as the source of model IDs, revisions, files, hashes, licenses, and capacity notes.

Preflight

1. Run bun run models:status before any setup.
2. If dependencies are missing and the checkout is clean, run bun install --frozen-lockfile --ignore-scripts. Preserve a dirty tree.
3. Read each model's state, file checks, smoke result, license state, and capacity warning. Do not infer readiness from file presence.

The default root is .spriteboy/models. Override it only with SPRITEBOY_MODELS_DIR. Keep weights, tokens, and generated manifests out of Git.

Set up BiRefNet

Run:

bun run models:setup -- --model birefnet-lite-512
bun run models:status -- --model birefnet-lite-512

The second command must report ready, verified hashes, and a passing ONNX smoke before calling the model ready. Report any capacity warning as-is. Rerun setup once without network access to prove the pinned local cache works.

Handle RMBG 2.0

Run status first. RMBG uses the gated license named by LOCAL_MODEL_CATALOG["rmbg-2.0"].license; show its pinned acceptance URL. When status says license-required, stop and ask the user to accept that license. Never accept it for the user or fabricate proof.

The current CLI has no supported license-acceptance or gated-token input. User approval alone does not make setup runnable. Until the web/control acceptance adapter exists, report this as blocked; do not create license-acceptance.json by hand. Once an adapter exists, verify its exact token variable and secret handling from code before use. Never put a token in an argument or print it.

Failures and cleanup

• installed-unverified: rerun setup so hash and ONNX smoke can finish.
• Hash mismatch: keep the model unavailable and report the named file.
• Smoke failure or memory limit: keep the model unavailable; include the bounded error and capacity note.
• Interrupted job: rerun with a new job. Do not claim the old job succeeded.
• Do not delete partial or verified files unless the user asks. If cleanup is requested, derive exact owned paths from the catalog, resolve the model root, show the list, and preserve user data.

Verification and claim limit

Run focused model tests after code changes, then bun run check. A model is ready only when current status reports ready, every required hash matches, and smoke passed. Report license-required, installed-unverified, failed, or capacity warnings without softening them.