jupytermind 0.3.0

package/src/ai_data_scientist/sensitivity.py

@@ -0,0 +1,445 @@
+"""Reusable sensitivity-analysis plans for conclusion-stability testing.
+
+Implements DES-AIDS-044 (REQ-AIDS-056): runs an analysis function
+across a grid of alternative specifications (model/parameter/subset
+choices) for a named target claim and reports whether the conclusion
+direction/magnitude is stable, bounded by an explicit evaluation budget.
+"""
+
+from __future__ import annotations
+
+import itertools
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class SensitivityBudgetExceededError(RuntimeError):
+    """Raised when a specification grid would exceed the run budget."""
+
+
+_UNSET = object()
+
+
+def _validate_target_claim(target_claim: str) -> None:
+    if not isinstance(target_claim, str):
+        raise TypeError("target_claim must be a string.")
+    if not target_claim.strip():
+        raise ValueError("target_claim must be a non-empty string.")
+
+
+# @id CODE-AIDS-079
+# @implements REQ-AIDS-056
+# @design DES-AIDS-044
+@dataclass(frozen=True, init=False)
+class SensitivityPlan:
+    """A grid of alternative specifications to re-run an analysis under."""
+
+    target_claim: str
+    parameter_grid: dict[str, list[Any]]
+    max_runs: int = 100
+
+    def __init__(
+        self,
+        *args: Any,
+        target_claim: Any = _UNSET,
+        parameter_grid: Any = _UNSET,
+        max_runs: Any = _UNSET,
+    ) -> None:
+        if args and isinstance(args[0], str):
+            if len(args) > 3:
+                raise TypeError("SensitivityPlan accepts at most 3 positional arguments.")
+            if target_claim is not _UNSET:
+                raise TypeError("SensitivityPlan got multiple values for target_claim.")
+            if len(args) > 1 and parameter_grid is not _UNSET:
+                raise TypeError("SensitivityPlan got multiple values for parameter_grid.")
+            if len(args) > 2 and max_runs is not _UNSET:
+                raise TypeError("SensitivityPlan got multiple values for max_runs.")
+            target_claim = args[0]
+            if len(args) > 1:
+                parameter_grid = args[1]
+            if len(args) > 2:
+                max_runs = args[2]
+        elif args:
+            if len(args) > 3:
+                raise TypeError("SensitivityPlan accepts at most 3 positional arguments.")
+            if parameter_grid is not _UNSET:
+                raise TypeError("SensitivityPlan got multiple values for parameter_grid.")
+            if len(args) > 1 and max_runs is not _UNSET:
+                raise TypeError("SensitivityPlan got multiple values for max_runs.")
+            if len(args) > 2 and target_claim is not _UNSET:
+                raise TypeError("SensitivityPlan got multiple values for target_claim.")
+            parameter_grid = args[0]
+            if len(args) > 1:
+                max_runs = args[1]
+            if len(args) > 2:
+                target_claim = args[2]
+        if target_claim is _UNSET:
+            raise TypeError("SensitivityPlan requires target_claim.")
+        if parameter_grid is _UNSET:
+            raise TypeError("SensitivityPlan requires parameter_grid.")
+        if max_runs is _UNSET:
+            max_runs = 100
+        object.__setattr__(self, "target_claim", target_claim)
+        object.__setattr__(self, "parameter_grid", parameter_grid)
+        object.__setattr__(self, "max_runs", max_runs)
+        _validate_target_claim(self.target_claim)
+
+    def specifications(self) -> tuple[dict[str, Any], ...]:
+        """Enumerate the Cartesian product of ``parameter_grid`` values."""
+        if not self.parameter_grid:
+            return ({},)
+        keys = list(self.parameter_grid.keys())
+        combos = itertools.product(*(self.parameter_grid[k] for k in keys))
+        specs = tuple(dict(zip(keys, combo, strict=True)) for combo in combos)
+        if len(specs) > self.max_runs:
+            raise SensitivityBudgetExceededError(
+                f"Specification grid has {len(specs)} combinations, "
+                f"exceeding max_runs={self.max_runs}."
+            )
+        return specs
+
+
+@dataclass(frozen=True, init=False)
+class SensitivityResult:
+    """Outcome of one specification run plus the overall stability verdict."""
+
+    target_claim: str
+    specification: dict[str, Any]
+    value: float
+    # GitHub #53 / REQ-AIDS-056: an evaluator failure is recorded as a
+    # failed specification instead of aborting the remaining plan.
+    failed: bool = False
+    error: str | None = None
+
+    def __init__(
+        self,
+        *args: Any,
+        target_claim: Any = _UNSET,
+        specification: Any = _UNSET,
+        value: Any = _UNSET,
+        failed: Any = _UNSET,
+        error: Any = _UNSET,
+    ) -> None:
+        if args and isinstance(args[0], str):
+            if len(args) > 5:
+                raise TypeError("SensitivityResult accepts at most 5 positional arguments.")
+            if target_claim is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for target_claim.")
+            if len(args) > 1 and specification is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for specification.")
+            if len(args) > 2 and value is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for value.")
+            if len(args) > 3 and failed is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for failed.")
+            if len(args) > 4 and error is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for error.")
+            target_claim = args[0]
+            if len(args) > 1:
+                specification = args[1]
+            if len(args) > 2:
+                value = args[2]
+            if len(args) > 3:
+                failed = args[3]
+            if len(args) > 4:
+                error = args[4]
+        elif args:
+            if len(args) > 5:
+                raise TypeError("SensitivityResult accepts at most 5 positional arguments.")
+            if specification is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for specification.")
+            if len(args) > 1 and value is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for value.")
+            if len(args) > 2 and failed is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for failed.")
+            if len(args) > 3 and error is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for error.")
+            if len(args) > 4 and target_claim is not _UNSET:
+                raise TypeError("SensitivityResult got multiple values for target_claim.")
+            specification = args[0]
+            if len(args) > 1:
+                value = args[1]
+            if len(args) > 2:
+                failed = args[2]
+            if len(args) > 3:
+                error = args[3]
+            if len(args) > 4:
+                target_claim = args[4]
+        if target_claim is _UNSET:
+            raise TypeError("SensitivityResult requires target_claim.")
+        if specification is _UNSET:
+            raise TypeError("SensitivityResult requires specification.")
+        if value is _UNSET:
+            raise TypeError("SensitivityResult requires value.")
+        if failed is _UNSET:
+            failed = False
+        if error is _UNSET:
+            error = None
+        object.__setattr__(self, "target_claim", target_claim)
+        object.__setattr__(self, "specification", specification)
+        object.__setattr__(self, "value", value)
+        object.__setattr__(self, "failed", failed)
+        object.__setattr__(self, "error", error)
+        _validate_target_claim(self.target_claim)
+
+
+@dataclass(frozen=True, init=False)
+class SensitivityReport:
+    """Aggregated result of running a plan: all outcomes and a stability verdict."""
+
+    target_claim: str
+    results: tuple[SensitivityResult, ...] = field(default_factory=tuple)
+    baseline_value: float | None = None
+    stable: bool = True
+    max_relative_deviation: float = 0.0
+    # GitHub #53: REQ-AIDS-056 requires classifying the conclusion as one of
+    # "stable", "attenuated", "reversed", or "not_comparable" rather than a
+    # bare relative-deviation threshold, which conflates a large same-signed
+    # change with a sign reversal and mishandles a near-zero baseline.
+    classification: str = "stable"
+    max_absolute_deviation: float = 0.0
+    sign_consistent: bool | None = None
+    magnitude_criterion: str = "relative_tolerance"
+
+    def __init__(
+        self,
+        *args: Any,
+        target_claim: Any = _UNSET,
+        results: Any = _UNSET,
+        baseline_value: Any = _UNSET,
+        stable: Any = _UNSET,
+        max_relative_deviation: Any = _UNSET,
+        classification: Any = _UNSET,
+        max_absolute_deviation: Any = _UNSET,
+        sign_consistent: Any = _UNSET,
+        magnitude_criterion: Any = _UNSET,
+    ) -> None:
+        fields = (
+            "results",
+            "baseline_value",
+            "stable",
+            "max_relative_deviation",
+            "classification",
+            "max_absolute_deviation",
+            "sign_consistent",
+            "magnitude_criterion",
+        )
+        values = {
+            "results": results,
+            "baseline_value": baseline_value,
+            "stable": stable,
+            "max_relative_deviation": max_relative_deviation,
+            "classification": classification,
+            "max_absolute_deviation": max_absolute_deviation,
+            "sign_consistent": sign_consistent,
+            "magnitude_criterion": magnitude_criterion,
+        }
+        if args and isinstance(args[0], str):
+            if len(args) > 9:
+                raise TypeError("SensitivityReport accepts at most 9 positional arguments.")
+            if target_claim is not _UNSET:
+                raise TypeError("SensitivityReport got multiple values for target_claim.")
+            for name, value in zip(fields, args[1:], strict=False):
+                if values[name] is not _UNSET:
+                    raise TypeError(f"SensitivityReport got multiple values for {name}.")
+            target_claim = args[0]
+            for name, value in zip(fields, args[1:], strict=False):
+                values[name] = value
+        elif args:
+            if len(args) > 9:
+                raise TypeError("SensitivityReport accepts at most 9 positional arguments.")
+            for name, value in zip(fields, args[: len(fields)], strict=False):
+                if values[name] is not _UNSET:
+                    raise TypeError(f"SensitivityReport got multiple values for {name}.")
+            for name, value in zip(fields, args[: len(fields)], strict=False):
+                values[name] = value
+            if len(args) > len(fields):
+                if target_claim is not _UNSET:
+                    raise TypeError("SensitivityReport got multiple values for target_claim.")
+                target_claim = args[len(fields)]
+        if target_claim is _UNSET:
+            raise TypeError("SensitivityReport requires target_claim.")
+        defaults = {
+            "results": (),
+            "baseline_value": None,
+            "stable": True,
+            "max_relative_deviation": 0.0,
+            "classification": "stable",
+            "max_absolute_deviation": 0.0,
+            "sign_consistent": None,
+            "magnitude_criterion": "relative_tolerance",
+        }
+        object.__setattr__(self, "target_claim", target_claim)
+        for name, value in values.items():
+            if value is _UNSET:
+                value = defaults[name]
+            object.__setattr__(self, name, value)
+        _validate_target_claim(self.target_claim)
+
+
+def _sign(value: float) -> int:
+    if value == 0:
+        return 0
+    return 1 if value > 0 else -1
+
+
+# @id CODE-AIDS-127
+# @implements REQ-AIDS-056
+# @design DES-AIDS-044
+def _classify_stability(
+    successful: list[SensitivityResult],
+    *,
+    baseline_value: float,
+    max_relative_deviation: float,
+    max_absolute_deviation: float,
+    stability_tolerance: float,
+    absolute_tolerance: float | None,
+) -> tuple[bool, str]:
+    """Return ``(sign_consistent, classification)`` for a non-empty ``successful``.
+
+    GitHub #53: classifies as ``"reversed"`` whenever successful values
+    disagree in sign (instead of a bare relative-deviation threshold, which
+    can mark a large same-signed drop "stable" and a small sign-consistent
+    change "unstable"), as ``"not_comparable"`` when the baseline is ``0``
+    and no ``absolute_tolerance`` was supplied (undefined relative
+    deviation), otherwise as ``"stable"``/``"attenuated"`` by whichever of
+    ``absolute_tolerance``/``stability_tolerance`` is configured.
+    """
+    signs = {_sign(r.value) for r in successful} - {0}
+    sign_consistent = len(signs) <= 1
+
+    if absolute_tolerance is not None:
+        within_tolerance = max_absolute_deviation <= absolute_tolerance
+    else:
+        within_tolerance = max_relative_deviation <= stability_tolerance
+
+    if not sign_consistent:
+        return sign_consistent, "reversed"
+    if baseline_value == 0 and absolute_tolerance is None:
+        return sign_consistent, "not_comparable"
+    if within_tolerance:
+        return sign_consistent, "stable"
+    return sign_consistent, "attenuated"
+
+
+# @id CODE-AIDS-080
+# @implements REQ-AIDS-056
+# @design DES-AIDS-044
+def run_sensitivity(
+    plan: SensitivityPlan,
+    analysis_fn: Callable[..., float],
+    stability_tolerance: float = 0.2,
+    absolute_tolerance: float | None = None,
+) -> SensitivityReport:
+    """Run ``analysis_fn`` across every specification in ``plan``.
+
+    ``analysis_fn`` is called once per specification as
+    ``analysis_fn(**specification)`` and must return a numeric
+    conclusion-relevant value; an exception it raises, or a non-finite
+    (``NaN``/``inf``) return value, is recorded on that specification's
+    ``SensitivityResult.failed``/``error`` instead of aborting the
+    remaining plan (REQ-AIDS-056). The first specification's value is
+    treated as the baseline.
+
+    The report's ``classification`` is one of:
+
+    - ``"reversed"``: at least one successful result's value has the
+      opposite sign from another (direction of the conclusion flips).
+    - ``"not_comparable"``: the baseline value is ``0`` and no
+      ``absolute_tolerance`` was given, so a relative deviation is
+      undefined (GitHub #53); or every specification failed.
+    - ``"stable"``: all successful values share a sign and the maximum
+      deviation from the baseline is within tolerance. Deviation is
+      measured by ``absolute_tolerance`` (against
+      ``max_absolute_deviation``) when given, otherwise by
+      ``stability_tolerance`` (against ``max_relative_deviation``); the
+      criterion actually used is recorded in ``magnitude_criterion``.
+    - ``"attenuated"``: all successful values share a sign but the
+      deviation exceeds the configured tolerance.
+
+    ``stable`` (bool) is kept for backward compatibility and is ``True``
+    exactly when ``classification == "stable"``.
+    """
+    specifications = plan.specifications()
+    results = []
+    for spec in specifications:
+        try:
+            value = float(analysis_fn(**spec))
+            if not math.isfinite(value):
+                # GitHub #53 follow-up (rubber-duck review): a non-finite
+                # value (NaN/inf) is not a meaningfully comparable
+                # conclusion value; treat it as a failed specification
+                # rather than letting it masquerade as "stable".
+                raise ValueError(f"analysis_fn returned a non-finite value: {value!r}")
+        except Exception as exc:  # noqa: BLE001 - recorded, not re-raised
+            results.append(
+                SensitivityResult(
+                    target_claim=plan.target_claim,
+                    specification=spec,
+                    value=float("nan"),
+                    failed=True,
+                    error=str(exc),
+                )
+            )
+        else:
+            results.append(
+                SensitivityResult(target_claim=plan.target_claim, specification=spec, value=value)
+            )
+    results = tuple(results)
+
+    if not results:
+        return SensitivityReport(
+            target_claim=plan.target_claim,
+            results=(),
+            baseline_value=None,
+            stable=False,
+            classification="not_comparable",
+        )
+
+    successful = [r for r in results if not r.failed]
+    if not successful:
+        return SensitivityReport(
+            target_claim=plan.target_claim,
+            results=results,
+            baseline_value=None,
+            stable=False,
+            classification="not_comparable",
+        )
+
+    baseline_value = successful[0].value
+    magnitude_criterion = (
+        "absolute_tolerance" if absolute_tolerance is not None else "relative_tolerance"
+    )
+
+    max_relative_deviation = 0.0
+    max_absolute_deviation = 0.0
+    for result in successful[1:]:
+        absolute_deviation = abs(result.value - baseline_value)
+        if baseline_value == 0:
+            relative_deviation = absolute_deviation
+        else:
+            relative_deviation = absolute_deviation / abs(baseline_value)
+        max_relative_deviation = max(max_relative_deviation, relative_deviation)
+        max_absolute_deviation = max(max_absolute_deviation, absolute_deviation)
+
+    sign_consistent, classification = _classify_stability(
+        successful,
+        baseline_value=baseline_value,
+        max_relative_deviation=max_relative_deviation,
+        max_absolute_deviation=max_absolute_deviation,
+        stability_tolerance=stability_tolerance,
+        absolute_tolerance=absolute_tolerance,
+    )
+
+    return SensitivityReport(
+        target_claim=plan.target_claim,
+        results=results,
+        baseline_value=baseline_value,
+        stable=classification == "stable",
+        max_relative_deviation=max_relative_deviation,
+        classification=classification,
+        max_absolute_deviation=max_absolute_deviation,
+        sign_consistent=sign_consistent,
+        magnitude_criterion=magnitude_criterion,
+    )

package/src/ai_data_scientist/signal_analysis.py

@@ -0,0 +1,201 @@
+"""Spectral signal analysis: baseline correction and peak/FWHM detection.
+
+Implements DES-AIDS-094 (REQ-AIDS-094, REQ-AIDS-095, REQ-AIDS-096): a
+first-class module for spectral/scientific-signal analysis (GitHub #74)
+operating on a generic 2-column ``x, y`` spectrum — baseline correction
+(linear two-point fit or Asymmetric Least Squares), a
+``scipy.signal.find_peaks``/``peak_widths`` wrapper returning
+``{position, fwhm, prominence, height}`` dicts, and a thin helper that
+builds a ``sensitivity.SensitivityPlan`` over
+``(prominence_frac, window)`` so a peak-count stability check requires
+no caller-written glue code around ``sensitivity.run_sensitivity``.
+"""
+
+from __future__ import annotations
+
+import numbers
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import numpy as np
+import scipy.sparse
+import scipy.sparse.linalg
+from scipy.signal import find_peaks, peak_widths, savgol_filter
+
+from ai_data_scientist.sensitivity import SensitivityPlan
+
+_SUPPORTED_BASELINE_METHODS = ("linear", "asls")
+
+# Fixed internal AsLS (Eilers & Boelens, 2005) parameters (DES-AIDS-094 /
+# ADR-0112): not part of the public signature, so behavior is fully
+# deterministic for a given x/y/method.
+_ASLS_LAM = 1e5
+_ASLS_P = 0.001
+_ASLS_N_ITER = 10
+
+
+# @id CODE-AIDS-146
+# @implements REQ-AIDS-094 REQ-AIDS-095
+# @design DES-AIDS-094
+def _coerce_xy(
+    x: Sequence[float], y: Sequence[float], *, min_len: int = 2
+) -> tuple[np.ndarray, np.ndarray]:
+    x_arr = np.array(x, dtype=float, copy=True)
+    y_arr = np.array(y, dtype=float, copy=True)
+    if x_arr.ndim != 1 or y_arr.ndim != 1:
+        raise ValueError("x and y must be 1-D sequences.")
+    if x_arr.shape[0] != y_arr.shape[0]:
+        raise ValueError("x and y must have equal length.")
+    if x_arr.shape[0] < min_len:
+        raise ValueError(f"x/y must have at least {min_len} elements.")
+    if not (np.all(np.isfinite(x_arr)) and np.all(np.isfinite(y_arr))):
+        raise ValueError("x and y must contain only finite values.")
+    return x_arr, y_arr
+
+
+# @id CODE-AIDS-141
+# @implements REQ-AIDS-094
+# @design DES-AIDS-094
+def _linear_baseline(x_arr: np.ndarray, y_arr: np.ndarray) -> np.ndarray:
+    if x_arr[0] == x_arr[-1]:
+        raise ValueError("x[0] and x[-1] must differ for a linear baseline fit.")
+    slope = (y_arr[-1] - y_arr[0]) / (x_arr[-1] - x_arr[0])
+    return y_arr[0] + slope * (x_arr - x_arr[0])
+
+
+# @id CODE-AIDS-142
+# @implements REQ-AIDS-094
+# @design DES-AIDS-094
+def _asls_baseline(y_arr: np.ndarray) -> np.ndarray:
+    n = y_arr.shape[0]
+    if n < 3:
+        raise ValueError("AsLS baseline correction requires at least 3 elements.")
+    diff_matrix = scipy.sparse.diags([1.0, -2.0, 1.0], offsets=[0, 1, 2], shape=(n - 2, n))
+    penalty = _ASLS_LAM * (diff_matrix.T @ diff_matrix)
+    weights = np.ones(n, dtype=float)
+    baseline = y_arr
+    for iteration in range(_ASLS_N_ITER):
+        weight_matrix = scipy.sparse.diags(weights, 0, shape=(n, n))
+        baseline = scipy.sparse.linalg.spsolve((weight_matrix + penalty).tocsc(), weights * y_arr)
+        if iteration < _ASLS_N_ITER - 1:
+            weights = np.where(y_arr > baseline, _ASLS_P, 1.0 - _ASLS_P)
+    return baseline
+
+
+# @id CODE-AIDS-143
+# @implements REQ-AIDS-094
+# @design DES-AIDS-094
+def baseline_correct(x: Sequence[float], y: Sequence[float], method: str = "linear") -> np.ndarray:
+    """Return ``y`` with an estimated baseline subtracted (GitHub #74).
+
+    ``method="linear"`` fits a straight line through the first and last
+    points; ``method="asls"`` uses Asymmetric Least Squares smoothing
+    with fixed internal parameters (``lam=1e5``, ``p=0.001``,
+    ``n_iter=10``). Neither ``x`` nor ``y`` is mutated.
+    """
+    if method not in _SUPPORTED_BASELINE_METHODS:
+        raise ValueError(f"Unsupported baseline_correct method: {method!r}")
+    min_len = 3 if method == "asls" else 2
+    x_arr, y_arr = _coerce_xy(x, y, min_len=min_len)
+    if method == "linear":
+        baseline = _linear_baseline(x_arr, y_arr)
+    else:
+        baseline = _asls_baseline(y_arr)
+    return y_arr - baseline
+
+
+# @id CODE-AIDS-147
+# @implements REQ-AIDS-095
+# @design DES-AIDS-094
+def _validate_window(window: Any, n: int) -> int:
+    if not isinstance(window, numbers.Integral) or isinstance(window, bool):
+        raise ValueError(  # noqa: TRY004 - ValueError required by REQ-AIDS-095
+            "window must be an odd integer (bool is not accepted)."
+        )
+    window = int(window)
+    if window % 2 == 0 or window < 5 or window > n:
+        raise ValueError(f"window must be an odd integer in [5, {n}]; got {window}.")
+    return window
+
+
+# @id CODE-AIDS-144
+# @implements REQ-AIDS-095
+# @design DES-AIDS-094
+def find_spectral_peaks(
+    x: Sequence[float],
+    y: Sequence[float],
+    prominence_frac: float = 0.05,
+    window: int | None = None,
+) -> list[dict[str, float]]:
+    """Return ``{position, fwhm, prominence, height}`` dicts for each peak.
+
+    ``x`` must be strictly increasing and uniformly spaced. When
+    ``window`` is given, ``y`` is Savitzky-Golay smoothed (``polyorder``
+    fixed at 3) before detection, and every returned value is computed
+    from that smoothed ``y`` (GitHub #74).
+    """
+    x_arr, y_arr = _coerce_xy(x, y, min_len=2)
+    diffs = np.diff(x_arr)
+    if not np.all(diffs > 0):
+        raise ValueError("x must be strictly increasing.")
+    dx = x_arr[1] - x_arr[0]
+    if not np.allclose(diffs, dx, rtol=1e-6, atol=0.0):
+        raise ValueError("x must be uniformly spaced.")
+
+    n = x_arr.shape[0]
+    if window is not None:
+        window = _validate_window(window, n)
+        y_arr = savgol_filter(y_arr, window_length=window, polyorder=3)
+
+    y_range = y_arr.max() - y_arr.min()
+    indices, properties = find_peaks(y_arr, prominence=prominence_frac * y_range)
+    if indices.size == 0:
+        return []
+
+    widths_samples, *_rest = peak_widths(y_arr, indices, rel_height=0.5)
+
+    peaks = []
+    for position_index, width_samples, prominence in zip(
+        indices, widths_samples, properties["prominences"], strict=True
+    ):
+        peaks.append(
+            {
+                "position": float(x_arr[position_index]),
+                "fwhm": float(width_samples * dx),
+                "prominence": float(prominence),
+                "height": float(y_arr[position_index]),
+            }
+        )
+    return peaks
+
+
+# @id CODE-AIDS-145
+# @implements REQ-AIDS-096
+# @design DES-AIDS-094
+def build_peak_sensitivity_plan(
+    x: Sequence[float],
+    y: Sequence[float],
+    prominence_fracs: list[float],
+    windows: list[int | None],
+    target_claim: str,
+    max_runs: int = 100,
+) -> tuple[SensitivityPlan, Callable[..., float]]:
+    """Return a ``(SensitivityPlan, analysis_fn)`` pair for peak-count stability.
+
+    ``analysis_fn`` calls :func:`find_spectral_peaks` with the captured
+    ``x``/``y`` and the specification's ``prominence_frac``/``window``,
+    returning the peak count as a ``float`` — so the pair can be passed
+    unchanged to ``sensitivity.run_sensitivity`` with no caller-written
+    glue code (GitHub #74).
+    """
+    plan = SensitivityPlan(
+        target_claim=target_claim,
+        parameter_grid={"prominence_frac": prominence_fracs, "window": windows},
+        max_runs=max_runs,
+    )
+
+    def analysis_fn(*, prominence_frac: float, window: int | None) -> float:
+        peaks = find_spectral_peaks(x, y, prominence_frac=prominence_frac, window=window)
+        return float(len(peaks))
+
+    return plan, analysis_fn

package/src/ai_data_scientist/skill_packaging.py

@@ -0,0 +1,40 @@
+"""Skill packaging metadata.
+
+Implements DES-AIDS-001 (REQ-AIDS-012): parses the GitHub Copilot Agent
+Skill manifest (YAML frontmatter + Markdown sections) so packaging can be
+verified the same way other `sdd-*` skills in this repository are
+discovered and loaded.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_SKILL_PATH = _REPO_ROOT / ".github" / "skills" / "ai-data-scientist" / "SKILL.md"
+
+_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n(.*)$", re.DOTALL)
+_FIELD_RE = re.compile(r'^(\w+):\s*"?(.*?)"?\s*$', re.MULTILINE)
+_SECTION_RE = re.compile(r"^#+\s+(.+)$", re.MULTILINE)
+
+
+# @id CODE-AIDS-012
+# @implements REQ-AIDS-012
+# @design DES-AIDS-001
+def load_skill_manifest(path: Path = DEFAULT_SKILL_PATH) -> dict:
+    """Parse a SKILL.md file's frontmatter and section headings."""
+    text = Path(path).read_text(encoding="utf-8")
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        raise ValueError(f"'{path}' is missing the required YAML frontmatter block.")
+
+    frontmatter_block, body = match.groups()
+    fields = dict(_FIELD_RE.findall(frontmatter_block))
+    sections = _SECTION_RE.findall(body)
+
+    return {
+        "name": fields.get("name", ""),
+        "description": fields.get("description", ""),
+        "sections": sections,
+    }