🥮 mooncakes.io

    moondriftkit

    Streaming histogram drift detection and stability reports for MoonBit.

    drift-detection
    histogram
    monitoring
    streaming
    data-quality
    Download zip
    Version
    0.2.0
    License
    Apache-2.0
    Repository
    Last updated
    3 months ago
    Downloads
    29

    No dependencies

    #MoonDriftKit

    MoonDriftKit is a MoonBit foundation library for streaming data drift detection, histogram stability reports, and deterministic monitoring evidence.

    It is designed for model input monitoring, feature distribution checks, telemetry quality gates, experiment guardrails, and data pipeline regression tests.

    #Core Features

    • Equal-width integer bucket specifications.
    • Compact baseline and current histograms.
    • Basis-point distribution shares for deterministic cross-backend results.
    • Drift reports with score, maximum bucket shift, shifted bucket count, and stable/watch/drift levels.
    • Fixed-size streaming windows for recent values.
    • Configurable drift policies for conservative or strict alerting.
    • Stable JSON export for CI logs, dashboards, and reproducible review evidence.
    • CLI demo for quick smoke testing.

    #Quick Example

    ///|
    test {
      let spec = BucketSpec::new(0, 100, 5)
      let reference = Histogram::new(spec).add_many([42, 45, 48, 51, 54])
      let current = Histogram::new(spec).add_many([70, 72, 75, 80, 86])
      let report = compare_histograms(reference, current)

      assert_true(report.is_alert())
      assert_eq(report.level_name(), "drift")
    }

    #Streaming Window

    ///|
    test {
      let spec = BucketSpec::new(0, 100, 5)
      let window = DriftWindow::new(spec, 3).push(10).push(20).push(30).push(90)

      assert_eq(window.length(), 3)
      assert_eq(window.histogram().total, 3)
    }

    #Policy Tuning

    ///|
    test {
      let spec = BucketSpec::new(0, 100, 5)
      let reference = Histogram::new(spec).add_many([10, 20, 30, 40, 50])
      let current = Histogram::new(spec).add_many([10, 20, 30, 60, 90])
      let report = compare_histograms_with_policy(
        reference,
        current,
        DriftPolicy::strict(),
      )

      assert_true(report.level == Drift)
    }

    #Design Notes

    MoonDriftKit intentionally uses integer basis points rather than platform floating point math. This keeps reports stable across JavaScript, WebAssembly, Wasm-GC, and native builds, which is important for CI and contest review.

    The default score is a symmetric population shift score:

    score_bp = sum(abs(current_share_bp - reference_share_bp)) / 2

    It is not a replacement for every statistical test. It is a small, inspectable foundation for practical drift gates and data quality signals.

    #Commands

    moon check --target all
moon test --target wasm
moon test --target wasm-gc
moon run cmd/main

    #Project Boundary

    MoonDriftKit does not provide plotting, dataframe storage, model training, or network ingestion. It focuses on the reusable drift-monitoring core that other MoonBit tools can embed.

    BucketDelta

    source
    pub(all) struct BucketDelta {
      index : Int
      lower : Int
      upper : Int
      reference_bp : Int
      current_bp : Int
      delta_bp : Int
    } derive(Eq, 
    Debug    )

    Per-bucket comparison in basis points.

    BucketSpec

    source
    pub(all) struct BucketSpec {
      min : Int
      max : Int
      buckets : Int
    } derive(Eq, 
    Debug    )

    Equal-width integer bucket specification.

    BucketSpec::bucket_count

    source
    fn BucketSpec::bucket_count(self : BucketSpec) -> Int

    BucketSpec::index_of

    source
    fn BucketSpec::index_of(self : BucketSpec, value : Int) -> Int

    BucketSpec::lower_bound

    source
    fn BucketSpec::lower_bound(self : BucketSpec, index : Int) -> Int

    BucketSpec::new

    source
    fn BucketSpec::new(min : Int, max : Int, buckets : Int) -> BucketSpec

    BucketSpec::upper_bound

    source
    fn BucketSpec::upper_bound(self : BucketSpec, index : Int) -> Int

    DriftLevel

    source
    pub(all) enum DriftLevel {
      Stable
      Watch
      Drift
    } derive(Eq, 
    Debug    )

    DriftPolicy

    source
    pub(all) struct DriftPolicy {
      watch_score_bp : Int
      drift_score_bp : Int
      watch_max_delta_bp : Int
      drift_max_delta_bp : Int
      watch_shifted_buckets : Int
      drift_shifted_buckets : Int
    } derive(Eq, 
    Debug    )

    Tunable thresholds for classifying drift reports.

    DriftPolicy::classify

    source
    fn DriftPolicy::classify(self : DriftPolicy, score_bp : Int, max_delta_bp : Int, shifted : Int) -> DriftLevel

    DriftPolicy::default

    source
    fn DriftPolicy::default() -> DriftPolicy

    DriftPolicy::strict

    source
    fn DriftPolicy::strict() -> DriftPolicy

    DriftReport

    source
    pub(all) struct DriftReport {
      level : DriftLevel
      score_bp : Int
      max_delta_bp : Int
      shifted_buckets : Int
      reference_total : Int
      current_total : Int
      buckets : Array[BucketDelta]
    } derive(Eq, 
    Debug    )

    Drift report comparing a baseline histogram with a current histogram.

    DriftReport::is_alert

    source
    fn DriftReport::is_alert(self : DriftReport) -> Bool

    DriftReport::level_name

    source
    fn DriftReport::level_name(self : DriftReport) -> String

    DriftReport::to_json

    source
    fn DriftReport::to_json(self : DriftReport) -> String

    DriftWindow

    source
    pub(all) struct DriftWindow {
      spec : BucketSpec
      capacity : Int
      values : Array[Int]
    } derive(Eq, 
    Debug    )

    Fixed-size integer window for streaming monitoring examples.

    DriftWindow::histogram

    source
    fn DriftWindow::histogram(self : DriftWindow) -> Histogram

    DriftWindow::length

    source
    fn DriftWindow::length(self : DriftWindow) -> Int

    DriftWindow::new

    source
    fn DriftWindow::new(spec : BucketSpec, capacity : Int) -> DriftWindow

    DriftWindow::push

    source
    fn DriftWindow::push(self : DriftWindow, value : Int) -> DriftWindow

    Histogram

    source
    pub(all) struct Histogram {
      spec : BucketSpec
      counts : Array[Int]
      total : Int
    } derive(Eq, 
    Debug    )

    Compact integer histogram used for baseline and current windows.

    Histogram::add

    source
    fn Histogram::add(self : Histogram, value : Int) -> Histogram

    Histogram::add_many

    source
    fn Histogram::add_many(self : Histogram, values : Array[Int]) -> Histogram

    Histogram::count_at

    source
    fn Histogram::count_at(self : Histogram, index : Int) -> Int

    Histogram::new

    source
    fn Histogram::new(spec : BucketSpec) -> Histogram

    Histogram::share_bp_at

    source
    fn Histogram::share_bp_at(self : Histogram, index : Int) -> Int

    Histogram::to_json

    source
    fn Histogram::to_json(self : Histogram) -> String

    compare_histograms

    source
    fn compare_histograms(reference : Histogram, current : Histogram) -> DriftReport

    compare_histograms_with_policy

    source
    fn compare_histograms_with_policy(reference : Histogram, current : Histogram, policy : DriftPolicy) -> DriftReport

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io