Skip to content

[SCR-380] Add an asset generation CLI - #381

Merged
itsryanarmani merged 1 commit into
mainfrom
scr-380-assetgen
Sep 12, 2026
Merged

itsryanarmani merged 1 commit into
mainfrom
scr-380-assetgen

Conversation

@itsryanarmani

@itsryanarmani itsryanarmani commented Sep 12, 2026 •

Copy link
Copy Markdown
Owner

Closes #380

What

Adds assetgen, a CLI for generating, cutting out, upscaling and slicing game art through WaveSpeed, with the cost controls a per-image spend needs.

Why

We produced a few hundred sprites by hand-driving the vendor CLI and hit the same failures twice. They belong in a tool.

The default route is counter-intuitive and worth stating plainly. Generating with a premium model is worse value than generating with a cheap one and upscaling:

Route Per asset Resolution Transparent
pipeline (flux-schnell + bgremove + real-esrgan) $0.0064 4096px yes
gpt-image-2.5 alone $0.024 1024px no

Roughly four times the price for a quarter of the pixels, and an opaque background either way.

Three failures are encoded rather than documented, because none of them raise an error:

  1. Text-to-image returns opaque RGB however often the prompt asks for a transparent background. A batch of 200 sprites with the backdrop baked in looks fine in a file listing.
  2. real-esrgan returns RGB JPEG and destroys alpha it was handed. The thumbnail still looks correct.
  3. wavespeed run --sync aborts the submission. Without it the CLI polls and succeeds.

Each of those cost a cycle to find, and each is invisible until you open an output file, so the tool asserts on the alpha channel rather than trusting a successful exit.

Cost controls, since this spends real money per image: an estimate before every run, --dry-run on every subcommand, --yes required above $1, existing outputs skipped so a re-run resumes instead of paying twice, and an abort after ten consecutive failures.

Codex produced a parallel implementation of this while I was writing it and the two collided in the same directory. I kept the version I had tested end to end and dropped the rest, including a test file that cannot run here (pytest will not install under PEP 668). Shipping tests I cannot execute is worse than shipping none, so there are none yet, and that is a gap.

How I verified

The full pipeline ran end to end, and the three-stage output is the evidence that each step does what it claims:

$ bash -c 'python3 assetgen/assetgen.py pipeline --prompt "a ripe red tomato, single object, centered" --name tomato --count 1 --out /tmp/ag2 | tail -3'
upscale: 1 image(s) x $0.0024 = $0.0024
upscale: 1 ok, 0 failed
spend ~$0.0024  ->  /tmp/ag2
-> pipeline completed, ok
$ bash -c 'python3 -c "
from PIL import Image
for p in [\"_raw/tomato-000.png\",\"_nobg/tomato-000.png\",\"tomato-000.png\"]:
    im=Image.open(\"/tmp/ag2/\"+p).convert(\"RGBA\")
    print(p, im.size, im.split()[-1].getextrema())"'
_raw/tomato-000.png (1024, 1024) (255, 255)
_nobg/tomato-000.png (1024, 1024) (0, 254)
tomato-000.png (4096, 4096) (0, 255)
-> opaque as generated, transparent after the cut, still transparent after 4x, ok

The first line is the failure this tool exists to prevent: that image was generated with "transparent background" in the prompt and came back fully opaque.

The dry run makes no API calls:

$ bash -c 'python3 assetgen/assetgen.py pipeline --prompt x --count 10 --dry-run'
pipeline: 10 x (generate $0.003 + bgremove $0.001 + upscale $0.0024) = $0.06
dry run, no API calls made
-> cost shown, nothing spent, ok

Separately, the upscale path has been run at scale: 236 sprites, 0 failures on verification, about $0.57.

Proof: n/a - a CLI whose output is verified by the alpha-channel assertions above rather than by a UI.

Operator: not applicable - a local developer tool with no deployed surface.

Assisted-by: claude-personal-3:claude-opus-5


Devin Review

Generate, cut the background out, upscale and slice game art through
WaveSpeed, with the cost controls a per-image spend needs.

The default route is generate-cheap-then-upscale. It costs about a
quarter of generating with a premium model and lands at four times the
resolution.

Three failures are encoded rather than documented, because each is
silent. Text-to-image returns opaque RGB however often the prompt asks
for transparency. The upscaler returns RGB and destroys alpha it was
given. Passing --sync to the vendor run command aborts the submission.
@coderabbitai

coderabbitai Bot commented Sep 12, 2026

Copy link
Copy Markdown

Warning

Review limit reached

Next included review available in 14 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 3 included reviews currently available. Your 73 included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 17df5bf0-d368-4b68-b065-148a5723706c

📥 Commits

Reviewing files that changed from the base of the PR and between d7eac7f and 33dd7eb.

📒 Files selected for processing (6)
  • assetgen/.gitignore
  • assetgen/README.md
  • assetgen/assetgen
  • assetgen/assetgen.py
  • assetgen/models.json
  • assetgen/styles.json

Comment @coderabbitai help to get the list of available commands.

@itsryanarmani
itsryanarmani merged commit 8265f1b into main Sep 12, 2026
4 of 6 checks passed
@itsryanarmani
itsryanarmani deleted the scr-380-assetgen branch September 12, 2026 18:32

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 3 potential issues.

5 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

Devin Review

Comment thread assetgen/assetgen.py
Comment on lines +105 to +107
if consecutive >= MAX_CONSECUTIVE_FAILURES:
print(f" aborting: {MAX_CONSECUTIVE_FAILURES} consecutive failures")
break

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Failure limit leaves batch running

After ten failures, each breaks iteration but leaves every queued task running. ThreadPoolExecutor.map eagerly submits all inputs, and context shutdown waits instead of cancelling pending futures. Remaining uploads and paid model calls continue despite the advertised abort.

Learn more

The iterator returned by ThreadPoolExecutor.map does not represent an unscheduled tail. The executor submits the input eagerly, so breaking result consumption does not prevent later work. The with block then calls shutdown(wait=True), allowing queued tasks to run before returning. Consequently, the ten-failure safeguard controls reporting but not remote operations or spending.

Example: A 200-file upscale batch gets ten failures first. The loop prints “aborting,” but tasks for later files remain queued and continue uploading and invoking WaveSpeed until the executor drains.

Recommended fix: Submit only a bounded window of futures. Stop scheduling after the threshold, cancel futures that have not started, and explicitly define whether already-running tasks may finish.

Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Comment thread assetgen/assetgen.py
Comment on lines +108 to +109
print(f"{label}: {done} ok, {failed} failed")
return done

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Failed batches exit successfully

When any item fails, each returns only the success count and the command still exits zero. cmd_pipeline also advances using whichever intermediate files exist. Automation accepts partial or empty output as a completed batch.

Learn more

each records failures locally, but its return value discards that information. Every command therefore reaches main normally even when all remote operations failed. In a pipeline, the next stage scans the previous stage’s directory and processes only successful files, so no later call restores the missing count. The final process status remains zero because no caller raises or returns a failure status.

Example: Generation of one requested asset fails. Background removal and upscaling each see zero files, the pipeline finishes normally, and a shell script receives exit status 0 without a final asset.

Recommended fix: Return a structured batch result containing successes, failures, and abort state. Make each command fail when any requested item failed, and make cmd_pipeline stop before the next stage unless the preceding stage produced every expected output.

Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Comment thread assetgen/assetgen.py
prompt = f"{args.prompt}. {style}" if style else args.prompt
out = Path(args.out)
out.mkdir(parents=True, exist_ok=True)
ref_url = upload(args.reference) if args.reference else None

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Failed reference uploads lose anchoring

When upload fails for --reference, cmd_generate silently omits image and starts paid generation. The requested style anchor is absent, so resulting assets can drift.

Suggested change
ref_url = upload(args.reference) if args.reference else None
ref_url = None
if args.reference:
ref_url = upload(args.reference)
if not ref_url:
sys.exit(f"failed to upload reference: {args.reference}")
Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed head: 33dd7ebc1b3bfe8ef46c083233ad9b17398e4425

Note on timing: PR #381 merged as 8265f1b at 2026-09-12T18:32:07Z, before this review cycle finished. My fix commit (ab6d924) was pushed to scr-380-assetgen afterward, so it did not land in main -- GitHub does not fold pushes to a branch back into an already-merged PR. main currently still has the bug described below. A human needs to either cherry-pick ab6d924 into a follow-up PR or apply the equivalent fix directly.

Findings

Major -- scope: this looks like it belongs in clis, not scripts. VISION.md's "Explicitly not this" section names exactly this shape of change: "A CLI for an ad-platform API. The README assigns those to the clis repo" and "Product source code ... no application code lives here." assetgen is a working CLI wrapping a single vendor's API (WaveSpeed) to generate game art -- it does not diagnose CI, enforce the PR standard, or manage the fleet, which is everything else in this repo. The root README's own repo table routes "Working CLIs for ad-platform APIs" to clis. This isn't something I can fix by editing code; flagging for a human decision (move it, or explicitly amend VISION.md's scope). Moot for blocking since the PR is already merged, but worth a deliberate follow-up rather than leaving it silently.

Major -- the failure-abort in each() doesn't stop the spend it promises to stop (fixed on the branch, not in main). assetgen/assetgen.py:96-108 (pre-fix): pool.map(fn, items) submits every item to the ThreadPoolExecutor eagerly (CPython's Executor.map builds the whole fs list before returning the result iterator), so breaking out of the consuming for loop after MAX_CONSECUTIVE_FAILURES only stops printing -- the with block's shutdown(wait=True) on exit still waits for every already-submitted item to run to completion. The README/PR body both advertise "ten consecutive failures aborts the batch" as a cost-control feature, but for e.g. generate --count 200 where the vendor API starts failing at item 20, all 200 API calls still fire and get billed; only the printed progress stops early. This code path is also untested in the PR's "How I verified" section (all recorded runs fully succeeded), so the gap wasn't visible. Fixed in ab6d924: submit futures individually and cancel() the ones not yet started once the threshold is hit.

Minor (not blocking)

  • cmd_pipeline (assetgen.py) re-implements the same "cost over $1 needs --yes" check inline instead of calling the existing gate() helper -- duplicated logic, not a bug.
  • No tests are included; the PR body discloses this explicitly as a known gap (pytest can't install here), so not re-flagging as new.
  • --reference (style-anchor) and the --yes-required-above-$1 gate are not exercised by any command in "How I verified"; low risk, just noting the coverage gap since it's adjacent to the abort-path gap above.
🧑‍⚖️ Council
Model Lens Result
GPT-5.6 (Codex) correctness error (openai HTTP 429, openrouter timed out) -- no findings produced
Kimi K3 (via OpenRouter) security no findings

Comment thread assetgen/assetgen.py
def each(items, fn, label):
done = failed = consecutive = 0
with ThreadPoolExecutor(max_workers=4) as pool:
for ok, name in pool.map(fn, items):

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major: pool.map(fn, items) submits every item to the thread pool eagerly (CPython builds the full futures list before returning the iterator). Breaking this loop after MAX_CONSECUTIVE_FAILURES only stops printing progress -- the with ThreadPoolExecutor block's implicit shutdown(wait=True) still runs every already-submitted item to completion, so the batch is not actually aborted and the vendor API calls (and their cost) still happen. This is the code path the "ten consecutive failures aborts the batch" cost control depends on, and it isn't exercised in the PR's verification runs (which all succeeded).

Fixed in commit ab6d924 on this branch: submit futures individually via pool.submit, and cancel() the ones not yet started once the threshold is hit. Note: since PR #381 already merged as 8265f1b before this fix was pushed, this commit did not make it into main -- a follow-up PR is needed to actually land it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add an asset generation CLI

1 participant