ria-toolkit-oss/src/ria_toolkit_oss/transforms/transforms.sigil

component Transforms {
  goal {
    Provide NumPy radio-data transforms used by the ML backends: data augmentations and channel/hardware impairment models over IQ.

    Own the functions that manipulate a signal while preserving its container type.
  }

  interface {
    Augmentations {
      Augmentations (iq_augmentations): generate_awgn, time_reversal, spectral_inversion, channel_swap, amplitude_reversal, drop_samples, quantize_tape, quantize_parts, magnitude_rescale, cut_out, patch_shuffle.
    }

    Impairments {
      Impairments (iq_impairments): add_awgn_to_signal, time_shift, frequency_shift, phase_shift, iq_imbalance, resample.
    }

    TypePreservingContract {
      Every function accepts an array or a Recording and returns the same type, preserving metadata for a Recording.
    }

    StandaloneSurface {
      This layer is a standalone library surface; the RIA Hub controller does not import it directly.
    }
  }
}

expand Transforms {
  constraints {
    Input must be a 2-D complex channels-by-samples array or a ValueError is raised; most transforms implement only the single-channel path and raise NotImplementedError for more channels.

    frequency_shift is relative to the sample rate and must be within -0.5 to 0.5; phase_shift must be within -pi to pi.

    AWGN is generated to match a target SNR in dB.
  }

  decisions {
    TypePreservingTransforms {
      Decision: Accept either a raw array or a Recording and return the same type, preserving metadata when the input is a Recording.

      Scope: Governs the call contract of every augmentation and impairment function.

      Design issues addressed: ML pipelines mix bare IQ arrays and Recording objects, and a transform must not strip a Recording's metadata as it passes through.

      Consequences: Callers can compose transforms without branching on input type or re-attaching metadata.
    }
  }
}