---

name: models description: "Wrap NumPy, PyTorch, TensorFlow, and JAX models with Foolbox, manage bounds and preprocessing, load samples, measure accuracy, compose model wrappers, and plot image batches." disable-model-invocation: true metadata: disco-role: operating root-skill: foolbox sub-skill: models license: MIT

Foolbox models

Use this route when the task involves turning a callable or framework model into a Foolbox model, choosing input bounds or channel layout, applying preprocessing, changing bounds, checking clean accuracy, loading Foolbox's bundled image samples, plotting image batches, thresholding inputs, or averaging randomized model calls. Trigger phrases include NumPyModel, PyTorchModel, TensorFlowModel, JAXModel, transform_bounds, accuracy, samples, plot.images, thresholding, and expectation over transformation (EOT).

This sub-skill covers model wrappers and their utility helpers. It does not select or execute attacks, download a model zoo, or define adversarial criteria. Route those tasks to the corresponding root-skill route if available.

Command and output paths

The helper path in this document is relative to the generated Foolbox skill root, not a native Foolbox checkout and not the caller's current directory. From any cwd, set the directory containing the root SKILL.md and change into it first:

# Replace this non-executable placeholder with the absolute directory containing the root SKILL.md.
export SKILL_ROOT=/path/to/installed/skills/disco/foolbox
cd "$SKILL_ROOT"

Use the actual skill-root path when it differs from this installation. Keep plots and other generated artifacts in an explicit absolute output directory or "$SKILL_ROOT/outputs/"; create that directory before writing and never write to the source/reference assets. The --plot-output value is a caller-chosen filesystem path, so make it absolute (or place it under that output directory) instead of relying on the process cwd.

Fast route

1. Identify the framework, the model's native input tensor type, channel order, and the model's raw input range (before any normalization).
2. Install Foolbox with python -m pip install foolbox; install only the needed optional framework separately (torch, tensorflow, or jax). Pillow is needed by samples() and Matplotlib by plot.images(); neither is needed to construct a basic model wrapper.
3. Construct the matching wrapper with a two-number bounds=(lower, upper). For PyTorch and TensorFlow, pass preprocessing in the model's input convention.
4. Call the wrapper on a native tensor or EagerPy tensor and confirm logits have shape (batch, classes). Use accuracy() and samples() before any downstream work.
5. If callers need another input range, use fmodel.transform_bounds(new_bounds). The default is non-mutating; do not confuse this conversion with clipping.
6. Add ThresholdingWrapper only when the model should receive a binary input, or ExpectationOverTransformationWrapper around a stochastic model when a multi-call mean is intended. Plot only four-dimensional image batches.

Framework choice and caveats

• NumPy: NumPyModel accepts any callable. It returns NumPy output when given NumPy input and has no inferable layout unless data_format is supplied. Explicitly pass channels_first or channels_last to samples() and plotting.
• PyTorch: PyTorchModel requires a torch.nn.Module, moves it to the selected device, defaults to CUDA when available otherwise CPU, and reports channels_first. Put the module in .eval() mode when deterministic behavior is wanted; construction warns if it is still training.
• TensorFlow: TensorFlowModel requires TensorFlow eager execution. Its device defaults to GPU when TensorFlow reports one, otherwise CPU, and its layout comes from tf.keras.backend.image_data_format().
• JAX: JAXModel accepts a callable and defaults to channels_last. JAX is optional; data_format=None is allowed at construction but reading the property then raises AttributeError, so specify a supported layout for data helpers.

Framework packages are intentionally optional because their builds differ by platform and accelerator. Never make an unrelated NumPy-only workflow import an optional framework. See API details and troubleshooting for failure-specific handling.

Operating checklist

• Treat bounds as the range of the inputs supplied to Foolbox, before mean, std, or flip_axis preprocessing.
• Use a negative axis for vector mean/std broadcasting: -3 is the channel axis for NCHW and -1 for NHWC. If axis is present, each provided mean/std must be one-dimensional.
• Keep model outputs as a batch of class scores with classes on the last axis; accuracy() computes argmax(axis=-1) and returns a Python float.
• For samples, use a supported bundled dataset name and remember that only the 20 bundled examples are available; batches above 20 repeat samples and warn.
• For plots, pass data_format whenever shape-based inference could be ambiguous and pass the same bounds used by the model.

Contract assumptions

Before writing code, record these values explicitly:

• the framework and the callable/model object that owns inference;
• the tensor layout (NCHW or NHWC) and the class-score output shape;
• the caller-facing bounds and the model-facing post-preprocessing scale;
• whether mean/std are scalar or channel vectors, and which negative axis broadcasts them;
• whether the model is deterministic, stochastic, or intentionally thresholded;
• whether sample assets and plotting dependencies are available in this runtime.

Prefer a small deterministic toy call before loading a pretrained model. Verify that the wrapper preserves the input backend, that logits have a final class axis, and that bounds conversion leaves equivalent logits approximately equal. Only then add framework device placement or a stochastic wrapper. Treat a clean accuracy value from the 20 bundled assets as a wiring check, not a model-quality claim.

Do not silently transpose arrays to repair a layout mismatch. Fix the model, data_format, preprocessing axis, and sample request as one contract. Do not put attacks, attack criteria, pretrained-weight downloads, or model-zoo loading instructions in this route.

Linked runtime material

• Verified constructors, preprocessing, bounds, and return types
• Self-contained wrapping and utility workflows
• Installation and runtime troubleshooting
• NumPy model smoke helper

Minimal validation

Run the helper from any cwd by first changing to the generated skill root (or replace the script path with the absolute $SKILL_ROOT path shown above):

cd "$SKILL_ROOT"
python sub-skills/models/scripts/smoke_models.py --help
python sub-skills/models/scripts/smoke_models.py

The second command uses only the NumPy path and bundled samples. Add --plot only when Matplotlib is installed. For a saved plot, pass an explicit output such as --plot-output "$SKILL_ROOT/outputs/model-smoke.png"; do not use an unqualified filename. The helper selects a headless backend unless the caller has already chosen one. It is a smoke check, not an attack benchmark and does not require an optional deep-learning framework.