Files
craft-ai-integrations/tools/mutation/mutation_burn_engine.py
e8f320321a feat(ai-engine-burn): InSPyReNet for Remove background, built in only (#112)
* feat(ai-engine-burn): InSPyReNet for image.matte (Remove background)

A second model on the Burn engine: `inspyrenet` answers `image.matte` from the
picture alone, a grayscale PNG at the picture's size (white is the subject, soft
along hair and fur). `remove-background` has had no local model; this is one.

- Network: InSPyReNet with the Swin-B backbone, written by hand in Burn after the
  MIT reference code. Module names follow the PyTorch keys, so the published
  .safetensors loads by name through Burn's PyTorch adapter. A load that leaves a
  weight unset, fails one, or finds a foreign tensor is refused in plain words.
- Any picture size: full resolution up to 1280 px on the long side; above that a
  reflect-padded square reduced with antialiased Lanczos-3, the matte enlarged
  back and refined at full resolution with a colour guided filter on the tiles
  near the edge (the Gyre approach), then a 0.2 fringe shrink.
- Weights: 1038lab/inspyrenet inspyrenet.safetensors at a pinned revision,
  checked tensor for tensor against the author's ckpt_base.pth.

Checked on one Windows machine (release): every stage against
transparent-background's PyTorch code (worst relative difference 3.2e-5 on the
processor, 2.4e-4 on the card, no pixel changing side); the shared conformance
suite; on a real PNG the mask is byte-identical to the same port in PhotoCraft.
Four new deliberate-bug cases in `be`, all caught. Not done: a catalogue recipe
(a recipe names a ComfyUI workflow today), clean timings, macOS and Linux runs,
a run through an app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(ai-features): a recipe that is built in only, InSPyReNet for Remove background

`LocalRecipe::comfyui` (default true) marks a recipe ComfyUI runs. With false it is only its
built-in routes: never a ComfyUI setup option, plan, install offer or connection, and engine
advice does not list ComfyUI for a tool without a ComfyUI recipe. `Feature::comfyui_recipes()`
gives those recipes; `engine_recipe`, `plan_native`, `setup_offer_native` and `enable_native`
are unchanged.

`remove-background` gets one such recipe: InSPyReNet on Burn, the pinned
`inspyrenet.safetensors` (1038lab/inspyrenet @ 0f594663, 367,120,444 bytes) in the folder
`inspyrenet`, so Set up AI offers one checked download and no ComfyUI.

Tests: the catalogue, setup options, plans and offers (`ai-features/tests/built_in_only.rs`),
registration and advice (`ai-client/tests/built_in_only.rs`), and through `AiClient` on Burn
(`ai-client/tests/burn_matte.rs`, the real run ignored). Mutation group `bo`: 8 of 8 caught.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(tools): retarget two `lc` mutation cases at the ComfyUI recipe lookups

`unrunnable-recipe-accepted` and `second-recipe-takes-plain-id` searched for the
`feature.locals` lookups in `ai-client/src/local.rs`, which now go through
`Feature::comfyui_recipes()`. Same mutations, new targets; group `lc`: 21 caught, one
known equivalent. Every case in `GROUPS` again has exactly one target (640 checked).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(ai-engine-burn): InSPyReNet runner checks around a stand-in, readout without panic

CI has no graphics card, only a software renderer (lavapipe, WARP), and the engine takes it.
There the tiny network was too slow for the conformance suite's poll limit, and on lavapipe the
readout failed. Unoptimised, Burn's processor backend takes minutes for the same network.

- The loaded model runs the pipeline around a `Predict`: the network, or in tests a stand-in,
  as the SAM 2.1 tests here use a fake backend. The conformance suite and the mask test use the
  stand-in (debug: the crate's unit tests in about 18 s).
- The tiny network still runs through load and run on the processor in an ignored release test
  (about 4 s). The runner's device choice is a field, so tests can name the processor.
- The prediction is read with `try_into_data`, so a device that fails while running is an
  error, not a guarded panic.
- docs/BURN-ENGINE.md: the test split and that a software renderer counts as a card.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(ai-engine-burn): InSPyReNet moves to the processor when the card fails

A card can answer the engine's probe and still fail on the network: on CI a software
renderer (lavapipe) failed while reading the answer back. The first failure on a card that is
not a cancel now builds the network again on the processor from the same file, runs that
picture again there with a notice, and stays on the processor (`inspyrenet/fallback.rs`).
A network loaded on the processor in the first place has nothing to move to.

Tests with stand-ins: a working card is kept; a failing one moves once and stays; a cancel
is not a failure; a rebuild that fails is the answer. Mutation group `be`: three new cases,
all seven InSPyReNet cases caught. A real photo on the card still runs on the card.

docs/BURN-ENGINE.md: the move, and the client run's picture is 2848 x 4272, not 3101 x 1613.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(ai-engine-burn): the move to the processor stays only after a rebuild that worked

The rebuild is tried once. If it fails, its error is the answer and later pictures go to the
card again, as `a_rebuild_that_fails_is_the_answer` already pins. The module docs and
docs/BURN-ENGINE.md said the model stays on the processor without that condition.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(ai-engine-burn): retry a failed InSPyReNet load on the card on the processor

The move to the processor covered failures while predicting, not a load on the card that
fails. `load_or_processor` now retries such a load on the processor, unless the file itself is
not the checkpoint (`Unsupported`), which is refused at once rather than read a second time.
A network loaded on the processor in the first place is loaded once.

Tests: a card that loads keeps the network; one that fails loads on the processor; a bad file
is not read twice; on the processor there is one load. Mutation group `be`: two new cases, all
nine InSPyReNet cases caught; every case in the checker has one target (645).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* style(ai-engine-burn): method references in the guided filter, one name for the fallback path

Three SonarCloud findings on #112: two closures in `guided.rs` become method references, and the
mutation cases name `inspyrenet/fallback.rs` once. No change in behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: imperator <imperator.maximus@gmail.com>
2026-10-30 19:34:26 +00:00

98 lines
6.2 KiB
Python

"""be: the Burn engine's own rules (saved-weights loading, the panic guard, the answer checks, the
file names it accepts), the catalogue route it is listed by, the binding's `.bpk` rule and the
shared revision; for InSPyReNet, the complete-weights rule, the matte size, the picture size and
the move to the processor when the card fails.
Not reached here, because they need the real model, a graphics card or a graph the converter
panics on (the ignored live tests in `crates/ai-engine-burn/tests/live.rs` and
`crates/ai-client/tests/burn_engine.rs` are not run by this checker): the picture-size check in
`encode`, the click-count check in `segment`, the choice between the graphics card and the
processor, the converter's panic guard in `runner/prepare.rs`, and the cargo feature wiring in
`ai-client`.
Case shape: name, file, old, new, package, target, test filter.
"""
B = 'crates/ai-engine-burn/src/'
PKG = 'craft-ai-engine-burn'
FALLBACK = 'inspyrenet/fallback.rs'
def lib(name, file, old, new, test):
"""A case run against the engine crate's own unit tests."""
return name, B + file, old, new, PKG, 'lib', test
BE = [
lib('burn-magic-unchecked', 'backend.rs', ' && &head == MAGIC', ' && true',
'only_a_file_that_starts'),
lib('burn-missing-weights-allowed', 'backend.rs',
'&& result.missing.is_empty()', '', 'a_load_that_left_a_weight'),
lib('burn-weight-errors-allowed', 'backend.rs',
'result.is_success() &&', '', 'a_load_that_left_a_weight'),
lib('burn-panic-not-guarded', 'backend.rs',
'catch_unwind(AssertUnwindSafe(work)).ok()', 'Some(work())', 'a_panic_in_guarded'),
lib('burn-wrong-length-answer-accepted', 'backend.rs',
'if masks.len() != PROPOSALS * side || scores.len() != PROPOSALS {', 'if false {',
'an_answer_of_the_wrong_size'),
lib('burn-best-proposal-ignored', 'backend.rs',
'let best = best_proposal(scores);', 'let best = 0;', 'best_rated'),
lib('burn-onnx-file-guessed', 'runner.rs',
'if weights.file_name() == Some(OsStr::new("encoder.onnx")) {', 'if false {',
'not_the_supported_export'),
lib('burn-prepare-decoder-not-required', 'runner/prepare.rs',
'filter(|d| d.join("decoder.onnx").is_file())', 'filter(|_| true)',
'no_decoder_says_what_is_missing'),
lib('burn-prepared-copy-inside-the-model-folder', 'runner/prepare.rs',
'source.parent().map(|p| p.join(PREPARED_DIR))', 'Some(source.join(PREPARED_DIR))',
'not_the_supported_export'),
lib('burn-decoder-not-required', 'runner.rs',
'd.join(DECODER_FILE).is_file() && weights.is_file()', 'weights.is_file()',
'not_both_files'),
lib('burn-encoder-name-not-checked', 'runner.rs',
'.filter(|_| weights.file_name() == Some(OsStr::new(ENCODER_FILE)));',
'.filter(|_| true);', 'not_both_files'),
lib('burn-nvidia-not-declared', 'runner.rs',
' GpuVendor::Nvidia,\n GpuVendor::Amd,', ' GpuVendor::Amd,\n GpuVendor::Amd,',
'is_the_burn_sam21'),
lib('burn-damaged-copy-not-explained', 'runner/prepare.rs',
'if error.message == craft_ai_burn_setup::DAMAGED_COPY {', 'if false {',
'a_damaged_saved_copy_is_explained'),
lib('inspyrenet-incomplete-weights-accepted', 'inspyrenet/weights.rs',
'result.is_success() && result.missing.is_empty() && result.unused.iter().all(|k| recomputed(k))',
'true', 'a_load_that_is_not_whole'),
lib('inspyrenet-foreign-tensors-accepted', 'inspyrenet/weights.rs',
'result.unused.iter().all(|k| recomputed(k))', 'true', 'a_load_that_is_not_whole'),
lib('inspyrenet-matte-size-unchecked', 'inspyrenet/pipeline/mod.rs',
'if pred.len() != p.in_w * p.in_h {', 'if false {', 'a_wrong_answer_from_the_network'),
lib('inspyrenet-picture-bytes-unchecked', 'inspyrenet/pipeline/mod.rs',
'.filter(|n| picture.bytes.len() == n * 3)', '.filter(|_| true)', 'bad_and_empty_pictures'),
lib('inspyrenet-cancel-moves-to-processor', FALLBACK,
'Err(error) if error.kind != ErrorKind::Cancelled => error,', 'Err(error) => error,',
'a_cancel_is_not_a_failure'),
lib('inspyrenet-never-moves-to-processor', FALLBACK,
'let Some(rebuild) = self.rebuild.take() else {', 'let Some(rebuild) = None::<Rebuild> else {',
'moves_to_the_processor'),
lib('inspyrenet-processor-not-kept', FALLBACK,
' self.current = rebuild()?;\n self.current.predict(input, ctx)',
' rebuild()?.predict(input, ctx)', 'moves_to_the_processor'),
lib('inspyrenet-card-load-not-retried', FALLBACK,
'Err(_) => Ok((processor()?, false)),', 'Err(error) => Err(error),',
'fails_to_load_loads_on_the_processor'),
lib('inspyrenet-bad-file-read-twice', FALLBACK,
'Err(error) if error.kind == ErrorKind::Unsupported => Err(error),',
'Err(error) if false => Err(error),', 'not_read_twice'),
('burn-revision-bumped-in-the-architecture', B + 'model/mod.rs',
'onnx-0.22.0-v1";', 'onnx-0.22.0-v2";', PKG, 'revision', 'the_architecture_and_the_saved'),
('burn-revision-bumped-in-the-cache-key', 'crates/ai-burn-setup/src/sam21.rs',
'onnx-0.22.0-v1";', 'onnx-0.22.0-v2";', PKG, 'revision', 'the_architecture_and_the_saved'),
('burn-route-lists-no-files', 'crates/ai-features/src/catalogue/sam21.rs',
' models: sam21_onnx_files(),\n note: Some("Selects by clicking on the picture, not by a description.".to_owned()),\n fast_on_processor: false,\n },\n ],',
' models: Vec::new(),\n note: Some("Selects by clicking on the picture, not by a description.".to_owned()),\n fast_on_processor: false,\n },\n ],',
'craft-ai-features', 'native_files', 'burns_sam_2_1_route'),
('burn-route-named-rten', 'crates/ai-features/src/catalogue/sam21.rs',
'provider: "burn".to_owned(),', 'provider: "rten".to_owned(),',
'craft-ai-features', 'native_files', 'burns_sam_2_1_route'),
('burn-bpk-refused-when-binding', 'crates/ai-client/src/local.rs',
'["safetensors", "onnx", "bpk"]', '["safetensors", "onnx"]',
'craft-ai-client', 'local_native', 'burn_route_is_registered'),
]