feat(core): registration primitives + app patch/batch & asset plumbing

[vboussot]

📚 Stacked on #16 (pr/audit). The diff is against pr/audit — review #16 first.

Summary

Adds the core building blocks the registration apps need and hardens the KonfAI Apps inference path.

Core: a vector-field-aware Flip augmentation, a Norm magnitude transform, an optional geometry (Attribute) channel threaded through the network forward, and a fail-fast guard when no checkpoint is supplied.

Apps: the per-app CLIs are refactored onto a single build_app_cli factory, --patch-size/--batch-size inference overrides are plumbed end-to-end, all non-checkpoint bundle assets are staged into the workspace (not just .py), and app-requirement installation becomes opt-in and hardened.

These are the primitives the stacked seg/reg apps (#18/#19) build on.

What changed

Core — registration primitives (konfai/)

• data/augmentation.py: Flip gains a vector_field: bool flag. A new _flip() helper (shared by _compute and _inverse) negates the component channel matching each flipped spatial axis (channel = tensor.dim() - 1 - dim) only when the tensor is a genuine displacement/vector field (tensor.shape[0] == tensor.dim() - 1). The default (vector_field=False) path and scalars/masks are unchanged; an inline comment flags the multi-contrast edge case the channel-count guard cannot distinguish.
• data/transform.py: new Norm transform. Reduces a stacked vector field over its trailing component axis via torch.linalg.norm(dim=-1) (e.g. a displacement-field ensemble [N,(D),H,W,C] → per-sample magnitudes [N,(D),H,W]), drops that axis from Origin/Spacing/Direction, and reports the reduced shape in transform_shape() (shape[:-1]) so patch planning stays correct. Intended to precede Variance/StandardDeviation.
• network/network.py: optional attributes channel through the forward. ModuleArgsDict.named_forward, Network.named_forward, and Network.get_layers now accept attributes: list[list[Attribute]] | None, thread a parallel attribute_branchs register alongside the tensor branches, recurse into nested ModuleArgsDict, and pass attributes= to leaf modules that declare accepts_attributes = True (all others keep the old call signature). The measure path sources them from each input batch_data_item.attribute, letting geometry-aware registration modules read Origin/Spacing/Direction during forward.
• predictor.py: safer load + fail-fast on missing weights. ModelComposite loads local checkpoints via safe_torch_load(...) instead of raw torch.load(..., weights_only=False), and Predictor now raises PredictorError when path_to_models is empty instead of silently running no model and producing no output.

Apps — CLI factory (konfai-apps/konfai_apps/cli.py + apps/*)

• New build_app_cli(...) factory produces a subcommand main() exposing a uniform operation set (<infer_command>/eval/uncertainty/pipeline) while keeping arguments domain-specific through hooks (resolve_app, add_selection, add_infer_knobs, resolve_infer). infer_command renames the inference verb per domain and with_uncertainty=False drops the uncertainty command. Shared arg builders: _add_app_io, _add_gt, _add_mask, _add_patch_overrides.
• Per-app CLIs migrated onto the factory: impact_synth (synthesize; ensemble/tta/mc knobs), mrsegmentator (segment; --folds), totalsegmentator (segment; --models, with_uncertainty=False).

Apps — inference overrides & metadata

• --patch-size / --batch-size overrides plumbed end-to-end: CLI (_add_patch_overrides, also wired into main_apps infer/pipeline) → KonfAIApp.infer/pipeline → install_inference(forced_patch_size=, forced_batch_size=) → _set_patch_size_and_batch_size. Precedence is explicit override → VRAM plan → config default; a single --patch-size value is broadcast to the config's spatial dimensionality (isotropic cube), and _set_patch_size_and_batch_size writes only the values supplied (no-op when both are None).
• patch_size surfaced as app metadata: parsed from app.json, exposed via AppRepositoryInfo.get_patch_size(), and returned in app_server.get_app_info for UI patch controls.
• Fine-tune --lr flag added to the fine-tune subparser, forwarded through fine_tune(...) to the existing Network.load(override_lr=...) resume-override path.

Apps — asset staging & requirement safety (app_repository.py)

• Stage all non-checkpoint assets. download_inference/download_evaluation/download_uncertainty now copy every bundle file except .pt (custom .py, elastix parameter maps, lookup tables, …) into the workspace, and the config file is written last so its patch/batch tweaks are never clobbered by a raw copy. New _all_repo_filenames() refreshes the file list from the HF tree (metadata-only, cache-backed) so lazily-populated snapshots don't miss assets, falling back to the local snapshot when offline.
• Opt-in, hardened requirement install. _install_requirements(..., install_requirements=False) defaults to a no-op, skips protected core packages (torch, torchvision, torchaudio, konfai, konfai-apps), and skips non-PEP 508 lines (-r, --extra-index-url, git+https, …) via an InvalidRequirement guard.
• HF force-update simplification. Dropped the manual deletion of the HF cache .locks directory (and its HF_HUB_CACHE/repo_folder_name imports) in LocalAppRepositoryFromHF, relying on snapshot_download.

Docs & misc

• App READMEs gain VRAM / performance sections; root README.md install hint uses .[imaging]; examples/README.md corrects the custom-module filename (UNetpp.py → Model.py).
• .gitignore stops ignoring apps/impact_reg / apps/impact_seg and adds build/.

Testing

New regression tests:

• tests/unit/test_augmentation_flip.py — vector-field round-trip identity, component-channel negation on flip, scalar data stays layout-only, and the default (vector_field=False) stays layout-only on vector data.
• tests/unit/test_transform_norm.py — trailing-axis reduction with geometry update, and transform_shape() dropping the trailing axis.
• tests/unit/test_resume_lr_override.py — resume without override keeps the decayed LR and restores the scheduler; with override the LR/scheduler restart from the requested value (incl. PolyLRScheduler).
• konfai-apps/tests/unit/test_app_repository.py — install_evaluation/install_uncertainty stage non-Python assets; _install_requirements is a no-op by default and skips protected / non-PEP 508 lines.

Review notes

• Stacked PR — base is pr/audit (#16); review only the pr/audit..pr/modif-core range.
• Backward compatible. Flip.vector_field defaults to False, Norm is new, and the network attributes argument is optional with leaf modules opted in via accepts_attributes — existing configs and models behave exactly as before.
• Behaviour changes to note: app requirement installation is now opt-in (previously ran during install); inference stages every non-.pt asset rather than only .py files (intentional, so registration bundles reach the workspace); and an empty checkpoint set is now a hard PredictorError instead of a silent no-op.
• Watch area: the Flip component-negation guard keys on channel-count == spatial-rank, so vector_field=True should only be set on configs whose augmented tensors are scalars/masks or true vector fields (see the inline comment on the multi-contrast case).