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

JSON uses names for simple nodes, such as "mean", and operator keys for configured nodes, such as {"ewma":{"alpha":0.1}}. Serialize through StatSpec or a modality root. Expressions use numeric literals and structured operators; decorators retain an explicit inner tree. Defaults follow encodeDefaults. Non-JSON formats retain generated serial names and field layouts.

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. Optimizer strategies live in com.eignex.kumulant.schema.optimizer; the specs here reference those as configuration.

Types

Accuracy

@Serializable

@SerialName(value = "Accuracy")

data class Accuracy(val numClasses: Int) : PairedStatSpec<WeightedMeanResult>

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

Adwin

@Serializable

@SerialName(value = "Adwin")

data class Adwin(val delta: Double = StatDefaults.ADWIN_DELTA, val maxBucketsPerSize: Int = StatDefaults.ADWIN_MAX_BUCKETS_PER_SIZE) : 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 = StatDefaults.AUC_NUM_BINS, val lowerBound: Double = StatDefaults.AUC_LOWER_BOUND, val upperBound: Double = StatDefaults.AUC_UPPER_BOUND) : 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 = StatDefaults.BAYESIAN_REGRESSION_PRIOR_VARIANCE, val link: Link = StatDefaults.regressionLink, val priorMean: ContiguousVector? = null, val priorCovariance: DenseMatrix? = null) : RegressionStatSpec<PrecisionRegressionResult>

Spec for BayesianRegressionStat: Gaussian linear regression with a configurable 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 = StatDefaults.BLOOM_FILTER_BITS, val hashes: Int = StatDefaults.BLOOM_FILTER_HASHES, val hasher: HasherRef = HasherRef.SplitMix64) : DiscreteStatSpec<BloomFilterResult>

Spec for BloomFilterStat: probabilistic set membership.

BucketHistogram

@Serializable

@SerialName(value = "BucketHistogram")

data class BucketHistogram(val edges: List<Double>) : SeriesStatSpec<SparseHistogramResult>

Spec for BucketHistogramStat: weighted counts over caller-chosen bucket edges, each bucket including its upper edge. Build evenly spaced edges with linearEdges.

ClassCounts

@Serializable

@SerialName(value = "ClassCounts")

data class ClassCounts(val numClasses: Int) : SeriesStatSpec<ClassCountsResult>

Spec for ClassCountsStat: weighted count per class over a discrete label stream.

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 = StatDefaults.COUNTER_RATE_TREAT_DECREASE_AS_RESET) : SeriesStatSpec<RateResult>

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

CountMinSketch

@Serializable

@SerialName(value = "CountMinSketch")

data class CountMinSketch(val depth: Int = StatDefaults.COUNT_MIN_SKETCH_DEPTH, val width: Int = StatDefaults.COUNT_MIN_SKETCH_WIDTH, val seed: Long = StatDefaults.COUNT_MIN_SKETCH_SEED, 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 = StatDefaults.CUSUM_TARGET, val referenceValue: Double = StatDefaults.CUSUM_REFERENCE_VALUE, val threshold: Double = StatDefaults.CUSUM_THRESHOLD) : SeriesStatSpec<CusumResult>

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

DDSketch

@Serializable

@SerialName(value = "DDSketch")

data class DDSketch(val relativeError: Double = StatDefaults.DD_SKETCH_RELATIVE_ERROR, val probabilities: List<Double> = StatDefaults.quantileProbabilities().toList(), val minIndexableValue: Double = StatDefaults.DD_SKETCH_MIN_INDEXABLE_VALUE, val maxIndexableValue: Double = StatDefaults.DD_SKETCH_MAX_INDEXABLE_VALUE) : 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 halfLifeMillis: Long) : SeriesStatSpec<DecayingMeanResult>

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

DecayingSum

@Serializable

@SerialName(value = "DecayingSum")

data class DecayingSum(val halfLifeMillis: Long) : SeriesStatSpec<DecayingSumResult>

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

DecayingVariance

@Serializable

@SerialName(value = "DecayingVariance")

data class DecayingVariance(val halfLifeMillis: Long) : SeriesStatSpec<DecayingVarianceResult>

Spec for DecayingVarianceStat: time-decayed running variance with half-life 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 = StatDefaults.TREE_RANDOM_SEED, val leafArm: SeriesStatSpec<ClassCountsResult>? = null) : 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 = StatDefaults.TREE_RANDOM_SEED, val leafArm: SeriesStatSpec<WeightedVarianceResult>? = null) : RegressionStatSpec<TreeRegressionResult>

Spec for DecisionTreeRegressionStat: online VFDT regression tree.

DiagonalRegression

@Serializable

@SerialName(value = "DiagonalRegression")

data class DiagonalRegression(val featureSize: Int, val priorPrecision: Double = StatDefaults.DIAGONAL_REGRESSION_PRIOR_PRECISION, val learningRate: ScalarExpr = StatDefaults.diagonalLearningRate(), val penalty: Penalty = StatDefaults.regressionPenalty, val link: Link = StatDefaults.regressionLink) : RegressionStatSpec<DiagonalRegressionResult>

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

DiscreteGroupStatSpec

@Serializable

@SerialName(value = "DiscreteGroupStatSpec")

data class DiscreteGroupStatSpec(val stats: Map<String, StatSpec>) : DiscreteStatSpec<GroupResult>

Serializable recipe for a nested com.eignex.kumulant.schema.runtime.DiscreteStatGroup.

DiscreteStatSpec

@Serializable(with = DiscreteStatSpecSerializer::class)

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 alpha: Double) : SeriesStatSpec<WeightedMeanResult>

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

EwmaVariance

@Serializable

@SerialName(value = "EwmaVariance")

data class EwmaVariance(val alpha: Double) : SeriesStatSpec<WeightedVarianceResult>

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

ExponentialSmoothing

@Serializable

@SerialName(value = "ExponentialSmoothing")

data class ExponentialSmoothing(val alpha: Double, val beta: Double = alpha, val phi: Double = StatDefaults.SMOOTHING_PHI, val period: Int = StatDefaults.SMOOTHING_PERIOD, val gamma: Double = alpha, val mode: SeasonalMode = StatDefaults.seasonalMode) : SeriesStatSpec<ExponentialSmoothingResult>

Spec for ExponentialSmoothingStat: exponential smoothing with a damped trend and optional seasonality. period 1 is Holt's method; a longer period adds a Holt-Winters seasonal cycle.

FrugalMad

@Serializable

@SerialName(value = "FrugalMad")

data class FrugalMad(val stepSize: Double = StatDefaults.FRUGAL_QUANTILE_STEP_SIZE) : SeriesStatSpec<MadResult>

Spec for FrugalMadStat: constant-memory adaptive median and MAD estimates.

FrugalQuantile

@Serializable

@SerialName(value = "FrugalQuantile")

data class FrugalQuantile(val q: Double, val stepSize: Double = StatDefaults.FRUGAL_QUANTILE_STEP_SIZE, val initialEstimate: Double = StatDefaults.FRUGAL_QUANTILE_INITIAL_ESTIMATE) : 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 = StatDefaults.GAUSSIAN_NAIVE_BAYES_VARIANCE_FLOOR) : RegressionStatSpec<GaussianNaiveBayesResult>

Spec for GaussianNaiveBayesStat: online Gaussian naive Bayes classifier.

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.

HyperLogLog

@Serializable

@SerialName(value = "HyperLogLog")

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

Spec for HyperLogLogStat: cardinality sketch with controllable precision.

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 = StatDefaults.TDIGEST_COMPRESSION) : SeriesStatSpec<MadResult>

Spec for MadStat: streaming median and median absolute deviation from one raw-value t-digest.

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.

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 = StatDefaults.PAGE_HINKLEY_DELTA, val threshold: Double = StatDefaults.PAGE_HINKLEY_THRESHOLD) : SeriesStatSpec<PageHinkleyResult>

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

PairedGroupStatSpec

@Serializable

@SerialName(value = "PairedGroupStatSpec")

data class PairedGroupStatSpec(val stats: Map<String, StatSpec>) : PairedStatSpec<GroupResult>

Serializable recipe for a nested com.eignex.kumulant.schema.runtime.PairedStatGroup.

PairedStatSpec

@Serializable(with = PairedStatSpecSerializer::class)

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 = StatDefaults.plattOptimizer()) : PairedStatSpec<PlattCalibratorResult>

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

RandomForestClassifier

@Serializable

@SerialName(value = "RandomForestClassifier")

data class RandomForestClassifier(val featureSize: Int, val numClasses: Int, val splitCandidates: List<SerializableSplit>, val nbrTrees: Int = StatDefaults.FOREST_SIZE, val config: ClassificationTreeConfig = ClassificationTreeConfig(), val bagging: Boolean = StatDefaults.FOREST_BAGGING, val randomSeed: Int = StatDefaults.TREE_RANDOM_SEED, val leafArm: SeriesStatSpec<ClassCountsResult>? = null) : 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 = StatDefaults.FOREST_SIZE, val config: RegressionTreeConfig = RegressionTreeConfig(), val bagging: Boolean = StatDefaults.FOREST_BAGGING, val randomSeed: Int = StatDefaults.TREE_RANDOM_SEED, val leafArm: SeriesStatSpec<WeightedVarianceResult>? = null) : 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.

RegressionGroupStatSpec

@Serializable

@SerialName(value = "RegressionGroupStatSpec")

data class RegressionGroupStatSpec(val stats: Map<String, StatSpec>) : RegressionStatSpec<GroupResult>

Serializable recipe for a nested com.eignex.kumulant.schema.runtime.RegressionStatGroup.

RegressionStatSpec

@Serializable(with = RegressionStatSpecSerializer::class)

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 = StatDefaults.RESERVOIR_HISTOGRAM_CAPACITY, 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.

SeriesStatSpec

@Serializable(with = SeriesStatSpecSerializer::class)

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 = StatDefaults.regressionOptimizer(), 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(with = StatSpecSerializer::class)

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 = StatDefaults.regressionOptimizer(), val biasOptimizer: OptimizerSpec = optimizer, val penalty: Penalty = StatDefaults.regressionPenalty, val link: Link = StatDefaults.regressionLink) : 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 = StatDefaults.TDIGEST_COMPRESSION, val probabilities: List<Double> = StatDefaults.quantileProbabilities().toList()) : SeriesStatSpec<TDigestResult>

Spec for TDigestStat: streaming t-digest quantile sketch.

UnivariateRegression

@Serializable

@SerialName(value = "UnivariateRegression")

data class UnivariateRegression(val penalty: Penalty = StatDefaults.regressionPenalty) : PairedStatSpec<UnivariateRegressionResult>

Spec for UnivariateRegressionStat: scalar OLS / Lasso / Ridge depending on penalty.

Variance

@Serializable

@SerialName(value = "Variance")

data object Variance : SeriesStatSpec<WeightedVarianceResult>

Spec for VarianceStat: weighted running variance (Welford).

VectorGroupStatSpec

@Serializable

@SerialName(value = "VectorGroupStatSpec")

data class VectorGroupStatSpec(val stats: Map<String, StatSpec>) : VectorStatSpec<GroupResult>

Serializable recipe for a nested com.eignex.kumulant.schema.runtime.VectorStatGroup.

VectorStatSpec

@Serializable(with = VectorStatSpecSerializer::class)

sealed interface VectorStatSpec<R : Result> : StatSpec

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