✨ Expose typed Python API for the seven wk-* operations

[vanandrew]

Summary

• Each warpkit.scripts.<name> module now exports a typed function (medic, unwrap_phase, compute_fieldmap, apply_warp, convert_warp, convert_fieldmap, compute_jacobian) and a frozen Result dataclass alongside the existing main() argparse entry point.
• New warpkit.api module re-exports all seven functions + result types for from warpkit.api import medic usage by library integrators (nipype, fmriprep, etc.).
• main() is a thin shim: parse argv → call the typed function → forward ValueError to parser.error. CLI behaviour is preserved exactly (SystemExit(2), same stderr text).

Why

To support library integration (nipype interface bindings being written next), we need a typed Python entry point per CLI tool that accepts kwargs, raises ValueError, and returns a result dataclass — instead of forcing callers to fabricate argv and catch SystemExit.

Changes

• warpkit/api.py — new public re-export module.
• warpkit/scripts/_metadata.py — new; centralises BIDS sidecar resolution, the either-or/mutex acquisition validation, image coercion (Path | str | Nifti1Image), and noise-frame trimming previously duplicated across three scripts.
• warpkit/scripts/_warp_io.py — no longer takes an argparse.ArgumentParser; read_input_frames / write_output raise ValueError and the CLI shims forward to parser.error. read_input_frames also accepts already-loaded Nifti1Image objects in addition to paths.
• warpkit/scripts/{medic,unwrap_phase,compute_fieldmap,apply_warp,convert_warp,convert_fieldmap,compute_jacobian}.py — each gains a typed function + Result dataclass; main() shrinks to ~argparse + try/except ValueError → parser.error.
• One existing test (test_write_output_per_frame_map_clears_vector_intent) updated to match the new write_output signature.

API shape

All seven functions are keyword-only and accept paths or nib.Nifti1Image for image inputs:

from warpkit.api import medic, MedicResult

result: MedicResult = medic(
    phase=[...],
    magnitude=[...],
    out_prefix="/tmp/sub-01_medic",
    tes=[14.0, 38.0, 62.0],
    total_readout_time=0.05,
    phase_encoding_direction="j",
    n_cpus=8,
)
# result.fieldmap_native, .displacement_map, .fieldmap are absolute Paths

Test plan

• uv run pytest -q — 207/207 passed
• uvx ruff check warpkit/ — clean
• uvx ruff format --check warpkit/ — clean
• uvx pyright warpkit/ — clean (only the pre-existing warpkit_cpp stub-resolution warning)
• Pre-commit hooks pass (ruff, format, pyright, gitmoji commit-msg)
• All 92 CLI argument-validation tests still pass — parser.error text/SystemExit semantics preserved

[Copilot]

Pull request overview

This PR exposes a typed, programmatic Python API for the existing seven wk-* CLI operations by adding keyword-only entry points that raise ValueError (instead of SystemExit) and return frozen result dataclasses, while keeping CLI behavior stable via thin main() shims.

Changes:

• Added typed entry-point functions + frozen Result dataclasses to script modules, with main() forwarding ValueError to parser.error.
• Introduced shared helpers in warpkit/scripts/_metadata.py and refactored _warp_io.py to validate via ValueError and accept in-memory Nifti1Image inputs.
• Added warpkit/api.py as a single re-export surface for library integrators; updated one test for the new write_output signature.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
warpkit/scripts/unwrap_phase.py	Adds typed unwrap_phase() + result dataclass; CLI becomes a shim catching ValueError.
warpkit/scripts/medic.py	Adds typed medic() + result dataclass; CLI shim; refactors call into distortion pipeline.
warpkit/scripts/convert_warp.py	Adds typed convert_warp() + result dataclass; CLI shim; avoids naming clash with utility converter.
warpkit/scripts/convert_fieldmap.py	Adds typed convert_fieldmap() + result dataclass; CLI shim with message mapping.
warpkit/scripts/compute_jacobian.py	Adds typed compute_jacobian() + result dataclass; CLI shim.
warpkit/scripts/compute_fieldmap.py	Adds typed compute_fieldmap() + result dataclass; CLI shim; centralizes acquisition resolution.
warpkit/scripts/apply_warp.py	Adds typed apply_warp() + result dataclass; refactors transform validation to raise ValueError.
warpkit/scripts/_warp_io.py	Refactors shared warp I/O to raise ValueError (no argparse dependency) and accept in-memory images.
warpkit/scripts/_metadata.py	New shared helpers for image coercion, acquisition metadata resolution, and noise-frame trimming.
warpkit/api.py	New re-export module for the typed API surface.
tests/test_scripts.py	Updates write_output() call site to match new signature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 94.51372% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.71%. Comparing base (3a7a96b) to head (c8cf620).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
warpkit/scripts/convert_fieldmap.py	91.22%	5 Missing ⚠️
warpkit/scripts/convert_warp.py	89.58%	5 Missing ⚠️
warpkit/scripts/_metadata.py	94.82%	3 Missing ⚠️
warpkit/scripts/apply_warp.py	95.31%	3 Missing ⚠️
warpkit/scripts/compute_jacobian.py	92.10%	3 Missing ⚠️
warpkit/scripts/compute_fieldmap.py	95.34%	2 Missing ⚠️
warpkit/scripts/medic.py	97.61%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #21      +/-   ##
==========================================
- Coverage   95.42%   94.71%   -0.71%     
==========================================
  Files          15       16       +1     
  Lines        1071     1249     +178     
==========================================
+ Hits         1022     1183     +161     
- Misses         49       66      +17     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.