schema.spec

The spec catalog: a pure-data recipe for every stat in the library. Each spec is a small serializable value carrying only configuration, with no live cells, locks, or concurrency mode. This is the vocabulary that travels on the wire; the live stats it describes are built from it in com.eignex.kumulant.schema.runtime.

The sealed tree

StatSpec is the sealed root. Below it sit one interface per modality, SeriesStatSpec, PairedStatSpec, VectorStatSpec, DiscreteStatSpec, and RegressionStatSpec, each carrying its result type as a phantom marker that threads through schema declaration and materialization without appearing on the wire. Every concrete spec is a data class, or a data object for the parameter-less ones, sitting under the modality it materializes into. Because the hierarchy is sealed, the whole catalog lives in this one package; that is a deliberate constraint, not an accident of layout.

Wire shape

Polymorphism is by name: each spec carries a serial discriminator matching its Kotlin class name, so any format with open polymorphism, JSON, CBOR, or Protobuf, puts the same type string on the wire. Defaults on each spec mirror the underlying stat's constructor defaults, so an encoded payload stays terse when the format is configured to omit defaults. Construction lives elsewhere on purpose: a spec is inert data, and turning it into a live stat happens through the materialize functions in com.eignex.kumulant.schema.runtime, with the concurrency mode supplied at that point rather than carried on the wire.

Beyond the leaf specs

The catalog also holds the composed specs. The wrappers behind the operators in com.eignex.kumulant.schema.ops are spec variants too, so a filtered or windowed stat serializes as one tree, and GroupStatSpec nests a whole sub-schema as a single entry. Weighting strategies live in com.eignex.kumulant.schema.decay and optimizer strategies in com.eignex.kumulant.schema.optimizer; the specs here reference those as configuration.

Types

Accuracy

@Serializable

@SerialName(value = "Accuracy")

data object Accuracy : PairedStatSpec<WeightedMeanResult>

Spec for AccuracyStat: weighted classification accuracy over (predictedClass, trueClass).

Adwin

@Serializable

@SerialName(value = "Adwin")

data class Adwin(val delta: Double = 0.002, val maxBucketsPerSize: Int = 5) : SeriesStatSpec<AdwinResult>

Spec for AdwinStat: ADWIN2 adaptive-windowing change detector.

ArgMax

@Serializable

@SerialName(value = "ArgMax")

data object ArgMax : SeriesStatSpec<ArgMaxResult>

Spec for ArgMaxStat: running maximum plus the timestamp at which it occurred.

ArgMin

@Serializable

@SerialName(value = "ArgMin")

data object ArgMin : SeriesStatSpec<ArgMinResult>

Spec for ArgMinStat: running minimum plus the timestamp at which it occurred.

Auc

@Serializable

@SerialName(value = "Auc")

data class Auc(val numBins: Int = 256, val lowerBound: Double = 0.0, val upperBound: Double = 1.0) : PairedStatSpec<AucResult>

Spec for AucStat: streaming AUC over a fixed-resolution score histogram.

BayesianRegression

@Serializable

@SerialName(value = "BayesianRegression")

data class BayesianRegression(val featureSize: Int, val priorVariance: Double = 1.0, val link: Link = Link.Identity) : RegressionStatSpec<CovarianceRegressionResult>

Spec for BayesianRegressionStat: closed-form Gaussian linear regression with isotropic prior.

BernoulliSum

@Serializable

@SerialName(value = "BernoulliSum")

data object BernoulliSum : SeriesStatSpec<BernoulliSumResult>

Spec for BernoulliSumStat: weighted count of nonzero inputs.

BloomFilter

@Serializable

@SerialName(value = "BloomFilter")

data class BloomFilter(val bits: Int = 1 shl 16, val hashes: Int = 7, val hasher: HasherRef = HasherRef.SplitMix64) : DiscreteStatSpec<BloomFilterResult>

Spec for BloomFilterStat: probabilistic set membership.

BrierScore

@Serializable

@SerialName(value = "BrierScore")

data object BrierScore : PairedStatSpec<WeightedMeanResult>

Spec for BrierScoreStat: mean squared error against y in {0, 1} for probabilistic predictions.

ConfusionMatrix

@Serializable

@SerialName(value = "ConfusionMatrix")

data class ConfusionMatrix(val numClasses: Int) : PairedStatSpec<ConfusionMatrixResult>

Spec for ConfusionMatrixStat: K-by-K weighted confusion matrix over (predictedClass, trueClass).

Count

@Serializable

@SerialName(value = "Count")

data object Count : SeriesStatSpec<SumResult>

Spec for CountStat: unweighted observation count.

CounterRate

@Serializable

@SerialName(value = "CounterRate")

data class CounterRate(val treatDecreaseAsReset: Boolean = true) : SeriesStatSpec<RateResult>

Spec for CounterRateStat: rate inferred from a monotonically increasing counter.

CountMinSketch

@Serializable

@SerialName(value = "CountMinSketch")

data class CountMinSketch(val depth: Int = 5, val width: Int = 1024, val seed: Long = -7046029254386353133L, val hasher: HasherRef = HasherRef.SplitMix64) : DiscreteStatSpec<CountMinSketchResult>

Spec for CountMinSketchStat: approximate frequency table for unbounded-cardinality streams.

Covariance

@Serializable

@SerialName(value = "Covariance")

data object Covariance : PairedStatSpec<CovarianceResult>

Spec for CovarianceStat: weighted covariance and Pearson correlation between two streams.

Crossing

@Serializable

@SerialName(value = "Crossing")

data class Crossing(val level: Double) : SeriesStatSpec<CrossingResult>

Spec for CrossingStat: counts upward and downward crossings of a configured level.

Cusum

@Serializable

@SerialName(value = "Cusum")

data class Cusum(val target: Double = 0.0, val referenceValue: Double = 0.5, val threshold: Double = 5.0) : SeriesStatSpec<CusumResult>

Spec for CusumStat: two-sided cumulative-sum change-point detector.

DDSketch

@Serializable

@SerialName(value = "DDSketch")

data class DDSketch(val relativeError: Double = 0.01, val probabilities: List<Double> = listOf(0.5, 0.75, 0.9, 0.95, 0.99, 0.999)) : SeriesStatSpec<SketchResult>

Spec for DDSketchStat. probabilities is a List on the wire because most formats serialize lists more cleanly than primitive arrays; converted to a DoubleArray at materialize time.

DecayingMean

@Serializable

@SerialName(value = "DecayingMean")

data class DecayingMean(val weighting: HalfLife) : SeriesStatSpec<DecayingMeanResult>

Spec for DecayingMeanStat: time-decayed running mean with HalfLife weighting.

DecayingRate

@Serializable

@SerialName(value = "DecayingRate")

data class DecayingRate(val halfLifeMillis: Long) : SeriesStatSpec<DecayingRateResult>

Spec for DecayingRateStat: events-per-second with exponential time decay.

DecayingSum

@Serializable

@SerialName(value = "DecayingSum")

data class DecayingSum(val weighting: HalfLife) : SeriesStatSpec<DecayingSumResult>

Spec for DecayingSumStat: time-decayed running sum with HalfLife weighting.

DecayingVariance

@Serializable

@SerialName(value = "DecayingVariance")

data class DecayingVariance(val weighting: HalfLife) : SeriesStatSpec<DecayingVarianceResult>

Spec for DecayingVarianceStat: time-decayed running variance with HalfLife weighting.

DecisionTreeClassifier

@Serializable

@SerialName(value = "DecisionTreeClassifier")

data class DecisionTreeClassifier(val featureSize: Int, val numClasses: Int, val splitCandidates: List<SerializableSplit>, val config: ClassificationTreeConfig = ClassificationTreeConfig(), val randomSeed: Int = 0) : RegressionStatSpec<TreeClassificationResult>

Spec for DecisionTreeClassifierStat: online VFDT classification tree.

DecisionTreeRegression

@Serializable

@SerialName(value = "DecisionTreeRegression")

data class DecisionTreeRegression(val featureSize: Int, val splitCandidates: List<SerializableSplit>, val config: RegressionTreeConfig = RegressionTreeConfig(), val randomSeed: Int = 0) : RegressionStatSpec<TreeRegressionResult>

Spec for DecisionTreeRegressionStat: online VFDT regression tree.

DiagonalRegression

@Serializable

@SerialName(value = "DiagonalRegression")

data class DiagonalRegression(val featureSize: Int, val priorPrecision: Double = 1.0, val learningRate: ScalarExpr = ConstantRate(1.0), val penalty: Penalty = Penalty.None, val link: Link = Link.Identity) : RegressionStatSpec<DiagonalRegressionResult>

Spec for DiagonalRegressionStat: factorised-Gaussian posterior with per-coordinate precision.

DiscreteStatSpec

@Serializable

sealed interface DiscreteStatSpec<R : Result> : StatSpec

StatSpec that materializes into a com.eignex.kumulant.core.DiscreteStat with result type R.

EwmaMean

@Serializable

@SerialName(value = "EwmaMean")

data class EwmaMean(val weighting: Alpha) : SeriesStatSpec<WeightedMeanResult>

Spec for EwmaMeanStat: exponentially-weighted moving average with per-observation Alpha.

EwmaVariance

@Serializable

@SerialName(value = "EwmaVariance")

data class EwmaVariance(val weighting: Alpha) : SeriesStatSpec<WeightedVarianceResult>

Spec for EwmaVarianceStat: exponentially-weighted moving variance with per-observation Alpha.

Excursion

@Serializable

@SerialName(value = "Excursion")

data object Excursion : SeriesStatSpec<ExcursionResult>

Spec for ExcursionStat: running peak with the largest peak-to-trough excursion observed.

FrugalQuantile

@Serializable

@SerialName(value = "FrugalQuantile")

data class FrugalQuantile(val q: Double, val stepSize: Double = 0.01, val initialEstimate: Double = 0.0) : SeriesStatSpec<QuantileResult>

Spec for FrugalQuantileStat: O(1)-memory single-quantile estimator.

GaussianNaiveBayes

@Serializable

@SerialName(value = "GaussianNaiveBayes")

data class GaussianNaiveBayes(val featureSize: Int, val numClasses: Int, val varianceFloor: Double = 1.0E-9) : RegressionStatSpec<GaussianNaiveBayesResult>

Spec for GaussianNaiveBayesStat: online Gaussian naive Bayes classifier.

GaussianScorer

@Serializable

@SerialName(value = "GaussianScorer")

data object GaussianScorer : SeriesStatSpec<GaussianScoreResult>

Spec for GaussianScorerStat: running mean / variance with |x - mean| / stdDev z-score.

GroupStatSpec

@Serializable

@SerialName(value = "GroupStatSpec")

data class GroupStatSpec(val stats: Map<String, StatSpec>) : SeriesStatSpec<GroupResult>

Serializable spec for a nested series-modality com.eignex.kumulant.schema.runtime.StatGroup. Holds a recursive map of StatSpec entries keyed by name; every entry must itself be a SeriesStatSpec; materialization happens in StatFactory.kt.

HalfSpaceTrees

@Serializable

@SerialName(value = "HalfSpaceTrees")

data class HalfSpaceTrees(val featureSize: Int, val featureRanges: List<FeatureRange>, val numTrees: Int = 25, val height: Int = 8, val windowSize: Int = 250, val randomSeed: Int = 0) : VectorStatSpec<HalfSpaceTreesResult>

Spec for HalfSpaceTreesStat: online ensemble of random half-space trees for multivariate anomaly scoring.

HdrHistogram

@Serializable

@SerialName(value = "HdrHistogram")

data class HdrHistogram(val lowestDiscernibleValue: Double = 0.001, val initialHighestTrackableValue: Double = 100.0, val significantDigits: Int = 3) : SeriesStatSpec<SparseHistogramResult>

Spec for HdrHistogramStat: high-dynamic-range histogram.

Holt

@Serializable

@SerialName(value = "Holt")

data class Holt(val alphaWeighting: Alpha, val betaWeighting: Alpha = alphaWeighting, val phi: Double = 1.0) : SeriesStatSpec<HoltResult>

Spec for HoltStat: double exponential smoothing with optional trend damping.

HyperLogLog

@Serializable

@SerialName(value = "HyperLogLog")

data class HyperLogLog(val precision: Int = 14, val hasher: HasherRef = HasherRef.SplitMix64) : DiscreteStatSpec<HyperLogLogResult>

Spec for HyperLogLogStat: cardinality sketch with controllable precision.

IsotonicCalibrator

@Serializable

@SerialName(value = "IsotonicCalibrator")

data class IsotonicCalibrator(val numBins: Int = 16) : PairedStatSpec<IsotonicCalibratorResult>

Spec for IsotonicCalibratorStat: binned isotonic calibrator over [0, 1].

LinearCounting

@Serializable

@SerialName(value = "LinearCounting")

data class LinearCounting(val bits: Int = 4096, val hasher: HasherRef = HasherRef.SplitMix64) : DiscreteStatSpec<LinearCountingResult>

Spec for LinearCountingStat: cardinality estimator backed by a bitset of bits cells.

LinearHistogram

@Serializable

@SerialName(value = "LinearHistogram")

data class LinearHistogram(val lowerBound: Double, val upperBound: Double, val binCount: Int) : SeriesStatSpec<SparseHistogramResult>

Spec for LinearHistogramStat: fixed-width bins over [lowerBound, upperBound).

LogLoss

@Serializable

@SerialName(value = "LogLoss")

data object LogLoss : PairedStatSpec<WeightedMeanResult>

Spec for LogLossStat: mean negative log-likelihood for binary y with predicted probability x.

Mad

@Serializable

@SerialName(value = "Mad")

data class Mad(val compression: Double = 100.0) : SeriesStatSpec<MadResult>

Spec for MadStat: streaming median and median absolute deviation via two t-digests.

MaeLoss

@Serializable

@SerialName(value = "MaeLoss")

data object MaeLoss : PairedStatSpec<WeightedMeanResult>

Spec for MaeLossStat: mean absolute error |y - yhat|.

Max

@Serializable

@SerialName(value = "Max")

data object Max : SeriesStatSpec<MaxResult>

Spec for MaxStat: running maximum.

Mean

@Serializable

@SerialName(value = "Mean")

data object Mean : SeriesStatSpec<WeightedMeanResult>

Spec for MeanStat: weighted running mean.

Min

@Serializable

@SerialName(value = "Min")

data object Min : SeriesStatSpec<MinResult>

Spec for MinStat: running minimum.

MinHash

@Serializable

@SerialName(value = "MinHash")

data class MinHash(val numHashes: Int = 128, val seed: Long = -3724518991637283867L, val hasher: HasherRef = HasherRef.SplitMix64) : DiscreteStatSpec<MinHashResult>

Spec for MinHashStat: Jaccard-similarity signature over numHashes independent hash functions.

Moments

@Serializable

@SerialName(value = "Moments")

data object Moments : SeriesStatSpec<MomentsResult>

Spec for MomentsStat: mean / variance / skewness / kurtosis (Welford).

MseLoss

@Serializable

@SerialName(value = "MseLoss")

data object MseLoss : PairedStatSpec<WeightedMeanResult>

Spec for MseLossStat: mean squared error (y - yhat)^2.

PageHinkley

@Serializable

@SerialName(value = "PageHinkley")

data class PageHinkley(val delta: Double = 0.005, val threshold: Double = 50.0) : SeriesStatSpec<PageHinkleyResult>

Spec for PageHinkleyStat: Page-Hinkley change-point detector.

PairedStatSpec

@Serializable

sealed interface PairedStatSpec<R : Result> : StatSpec

StatSpec that materializes into a com.eignex.kumulant.core.PairedStat with result type R.

PairedSum

@Serializable

@SerialName(value = "PairedSum")

data object PairedSum : PairedStatSpec<PairedSumResult>

Spec for PairedSumStat: tracks per-axis sums of (x, y) updates.

PinballLoss

@Serializable

@SerialName(value = "PinballLoss")

data class PinballLoss(val tau: Double) : PairedStatSpec<WeightedMeanResult>

Spec for PinballLossStat: quantile (pinball) loss at quantile tau.

PitHistogram

@Serializable

@SerialName(value = "PitHistogram")

data class PitHistogram(val numBins: Int) : SeriesStatSpec<SparseHistogramResult>

Spec for pitHistogram(numBins): PIT-style equiprobable histogram for calibration checks.

PlattCalibrator

@Serializable

@SerialName(value = "PlattCalibrator")

data class PlattCalibrator(val optimizer: OptimizerSpec = Sgd(ConstantRate(1e-2))) : PairedStatSpec<PlattCalibratorResult>

Spec for PlattCalibratorStat: one-feature logistic regression fitting sigmoid(a*x + b).

QuantileFilter

@Serializable

@SerialName(value = "QuantileFilter")

data class QuantileFilter(val probability: Double = 0.99, val relativeError: Double = 0.01) : SeriesStatSpec<QuantileFilterResult>

Spec for QuantileFilterStat: DDSketch-backed quantile-threshold anomaly detector.

RandomForestClassifier

@Serializable

@SerialName(value = "RandomForestClassifier")

data class RandomForestClassifier(val featureSize: Int, val numClasses: Int, val splitCandidates: List<SerializableSplit>, val nbrTrees: Int = 10, val config: ClassificationTreeConfig = ClassificationTreeConfig(), val bagging: Boolean = true, val randomSeed: Int = 0) : RegressionStatSpec<ForestClassificationResult>

Spec for RandomForestClassifierStat: ensembled VFDT classification forest.

RandomForestRegression

@Serializable

@SerialName(value = "RandomForestRegression")

data class RandomForestRegression(val featureSize: Int, val splitCandidates: List<SerializableSplit>, val nbrTrees: Int = 10, val config: RegressionTreeConfig = RegressionTreeConfig(), val bagging: Boolean = true, val randomSeed: Int = 0) : RegressionStatSpec<ForestRegressionResult>

Spec for RandomForestRegressionStat: ensembled VFDT regression forest.

Range

@Serializable

@SerialName(value = "Range")

data object Range : SeriesStatSpec<RangeResult>

Spec for RangeStat: running min and max as a pair.

Rate

@Serializable

@SerialName(value = "Rate")

data object Rate : SeriesStatSpec<RateResult>

Spec for RateStat: events per second over the observed wall-clock span.

Recency

@Serializable

@SerialName(value = "Recency")

data object Recency : SeriesStatSpec<RecencyResult>

Spec for RecencyStat: time elapsed since the most recent observation.

RecursiveVariance

@Serializable

@SerialName(value = "RecursiveVariance")

data class RecursiveVariance(val omega: Double, val alpha: Double, val beta: Double) : SeriesStatSpec<RecursiveVarianceResult>

Spec for RecursiveVarianceStat: sigma^2_t = omega + alpha * value^2 + beta * sigma^2_{t-1}.

RegressionStatSpec

@Serializable

sealed interface RegressionStatSpec<R : Result> : StatSpec

StatSpec that materializes into a com.eignex.kumulant.core.RegressionStat with result type R.

Reliability

@Serializable

@SerialName(value = "Reliability")

data class Reliability(val numBins: Int) : PairedStatSpec<ReliabilityResult>

Spec for ReliabilityStat: per-bin calibration table (mean predicted vs observed frequency).

ResampleAggregator

@Serializable

enum ResampleAggregator : Enum<ResampleAggregator>

Per-bucket reduction used by the ResampleByTimeSeries spec when aligning an input series onto fixed wall-clock buckets. Configured on a spec; the materializer threads it through to the runtime bucket aggregator.

ReservoirHistogram

@Serializable

@SerialName(value = "ReservoirHistogram")

data class ReservoirHistogram(val capacity: Int = 1024, val seed: Long) : SeriesStatSpec<ReservoirResult>

Configuration for ReservoirHistogramStat. Seed has no default - the live constructor's Random.Default.nextLong() is non-deterministic, which would silently produce different goldens on each instantiation if mirrored here.

RunLength

@Serializable

@SerialName(value = "RunLength")

data object RunLength : SeriesStatSpec<RunLengthResult>

Spec for RunLengthStat: current and longest consecutive truthy-run lengths.

SeasonalSmoothing

@Serializable

@SerialName(value = "SeasonalSmoothing")

data class SeasonalSmoothing(val alphaWeighting: Alpha, val betaWeighting: Alpha, val gammaWeighting: Alpha, val period: Int, val mode: SeasonalMode = SeasonalMode.Additive, val phi: Double = 1.0) : SeriesStatSpec<SeasonalSmoothingResult>

Spec for SeasonalSmoothingStat: triple exponential smoothing (Holt-Winters).

SeriesStatSpec

@Serializable

sealed interface SeriesStatSpec<R : Result> : StatSpec

StatSpec that materializes into a com.eignex.kumulant.core.SeriesStat with result type R.

SoftmaxRegression

@Serializable

@SerialName(value = "SoftmaxRegression")

data class SoftmaxRegression(val featureSize: Int, val numClasses: Int, val optimizer: OptimizerSpec = Sgd(), val biasOptimizer: OptimizerSpec = optimizer) : RegressionStatSpec<SoftmaxRegressionResult>

Spec for SoftmaxRegressionStat: multinomial (K-way) logistic regression.

Sojourn

@Serializable

@SerialName(value = "Sojourn")

data class Sojourn(val states: List<Long>) : DiscreteStatSpec<SojournResult>

Spec for SojournStat: per-state time, transition counts, and current dwell over a declared alphabet.

SpaceSaving

@Serializable

@SerialName(value = "SpaceSaving")

data class SpaceSaving(val capacity: Int) : DiscreteStatSpec<HeavyHittersResult>

Spec for SpaceSavingStat: top-capacity heavy-hitters tracker.

StatSpec

@Serializable

sealed interface StatSpec

Pure-data recipe for a com.eignex.kumulant.core.Stat. Each variant is a data class (or data object for parameter-less stats) whose fields are exactly the stat's configuration surface - no live cells, no locks, no com.eignex.kumulant.core.Concurrency.

StochasticRegression

@Serializable

@SerialName(value = "StochasticRegression")

data class StochasticRegression(val featureSize: Int, val optimizer: OptimizerSpec = Sgd(), val biasOptimizer: OptimizerSpec = optimizer, val penalty: Penalty = Penalty.None, val link: Link = Link.Identity) : RegressionStatSpec<StochasticRegressionResult>

Spec for StochasticRegressionStat: online GLM with a configurable optimizer.

Sum

@Serializable

@SerialName(value = "Sum")

data object Sum : SeriesStatSpec<SumResult>

Spec for SumStat: weighted running sum.

Summary

@Serializable

@SerialName(value = "Summary")

data object Summary : SeriesStatSpec<SummaryResult>

Spec for SummaryStat: mean / variance / min / max in one result, useful as a primary for mixed-scaler feedback projections.

TDigest

@Serializable

@SerialName(value = "TDigest")

data class TDigest(val compression: Double = 100.0, val probabilities: List<Double> = listOf(0.5, 0.75, 0.9, 0.95, 0.99, 0.999)) : SeriesStatSpec<TDigestResult>

Spec for TDigestStat: streaming t-digest quantile sketch.

ThresholdBucket

@Serializable

@SerialName(value = "ThresholdBucket")

data class ThresholdBucket(val thresholds: List<Double>) : SeriesStatSpec<ThresholdBucketResult>

Spec for ThresholdBucketStat: weighted counts per user-defined value bucket.

TotalWeights

@Serializable

@SerialName(value = "TotalWeights")

data object TotalWeights : SeriesStatSpec<SumResult>

Spec for TotalWeightsStat: cumulative observation weight.

UnivariateRegression