kumulant API reference
Kumulant is a streaming machine-learning library for Kotlin Multiplatform. Every model runs online: feed observations into an accumulator one at a time, ask for a result whenever you want one, and memory stays bounded no matter how long the stream runs. Two accumulators of the same shape can be merged into one, so partial results from parallel workers stitch back together without re-reading inputs.
Mental model
Every accumulator implements com.eignex.kumulant.core.Stat. The main operations and configuration are:
update(...)folds a single observation into the running state. The exact signature depends on the modality (see the stat package for the five modality interfaces).read()materialises the current state as an immutable Result snapshot without adding an observation. Snapshot consistency follows the stat's concurrency contract.merge(snapshot)folds another accumulator's snapshot into this one. Snapshots are the merge unit, not live accumulators; that is what lets merge cross a process boundary.concurrency: Concurrencyrecords the thread-safety contract the stat was built for. See com.eignex.kumulant.core.Concurrency.
reset() returns the stat to its construction baseline. create() spawns a fresh accumulator with the same configuration, optionally overriding the concurrency mode.
val mean = MeanStat()
for (x in doubleArrayOf(1.0, 2.0, 3.0)) mean.update(x)
val snapshot = mean.read()
println(snapshot.mean) // 2.0
val peer = MeanStat()
for (x in doubleArrayOf(4.0, 5.0)) peer.update(x)
mean.merge(peer.read())
println(mean.read().mean) // 3.0The compile-checked version of this example lives at com.eignex.kumulant.samples.basicMeanLifecycle, pulled into the rendered API docs via @sample directives on individual classes.
What's in the library
com.eignex.kumulant.core: the Stat and Result interfaces, the Concurrency enum, and the cross-cutting result traits.
com.eignex.kumulant.stat: concrete accumulators grouped by family: summary, quantile, cardinality, sketch, rate, decay, regression (with glm and tree subfamilies), score, calibration, anomaly, event, change, forecast.
com.eignex.kumulant.schema.ops: composable spec operators that change how a stat sees its input (filtering, weighting, windowing, sampling, lagging) or how it reports its output (folding, transforming, projecting). Materialize the composed spec to build its live adapters.
com.eignex.kumulant.schema: typed, named, wire-portable schemas. Declare a bag of stats once, materialise it into a live StatGroup, encode the schema to wire and rehydrate on the other side.
com.eignex.kumulant.bandit: multi-armed and contextual bandits built on the same Stat/Result foundation.
Conventions
Each built-in stat has a corresponding spec in com.eignex.kumulant.schema.spec, carrying configuration only. Specs are serializable through the spec roots. JSON uses compact node names and operator keys; other formats, including CBOR and Protobuf, retain the generated class tags and field layouts.
Concrete stat KDoc includes a summary, Use cases, Memory, Update, and Concurrency sections. See com.eignex.kumulant.stat.summary.MeanStat for the canonical shape.
Results are snapshots that can be serialized and passed to
merge(). Each stat documents its merge approximations and any state omitted from the snapshot.
Packages
Contextual bandits: each round comes with a feature vector, and the reward depends on both the chosen arm and the context. RegressionContextualBandit composes a regressor and posterior scoring rule for linear, tree, or forest reward models.
Indexless multi-armed bandits. Each round, the bandit picks one of K arms via choose(), the caller observes a reward, and update(arm, value, weight) folds it back into that arm's accumulator. No per-round feature vector; for that, see com.eignex.kumulant.bandit.contextual.
Distribution sampling, stream-hash functions, and Cholesky factorization used by statistical models. Vector and matrix storage, arithmetic, and triangular solves live in the separate koblas BLAS library (com.eignex.koblas).
The serializable expression AST used by the input operations in com.eignex.kumulant.schema. When an operation needs a projection or a predicate that must travel on the wire rather than as a live Kotlin lambda, it carries one of these trees instead. The whole tree is serializable, so a filter or a transform round-trips as data and rebuilds an identical closure on the far side.
The composition operators for the wire specs in com.eignex.kumulant.schema. Each operator is an extension on a modality-specific spec that returns another spec, so compositions stay pure data and round-trip on the wire exactly like the leaf specs they wrap. Materialization builds the internal live adapters from the composed spec; callers author compositions through this package.
The wire-portable optimizer strategies that the online linear-model stats take to pick their per-coordinate update rule. An OptimizerSpec is pure configuration: it carries the learning-rate schedule and the optimizer's hyperparameters, and materializes into a live optimizer in com.eignex.kumulant.stat.regression when the stat is built. As with every spec, the concurrency mode is supplied at materialize time rather than stored on the wire.
Turns the pure-data specs of com.eignex.kumulant.schema into live, running accumulators. The specs in the parent package say what to build; this package builds it, groups the results, and fans every update out to the right stat. Nothing here goes on the wire: it is the materialization and grouping layer that sits between a decoded schema and the live stats it stands up.
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.
Probability calibration diagnoses how predicted probabilities differ from observed positive rates and fits a mapping to correct them. The live stats consume com.eignex.kumulant.core.PairedStat observations (prediction, label); isotonic calibration derives a curve from a reliability snapshot.
Approximate distinct-count estimation. HyperLogLogStat takes a stream of opaque Long keys (com.eignex.kumulant.core.DiscreteStat) and answers "how many distinct keys have I seen?" in bounded memory. The right pre-step is to hash domain-specific keys through com.eignex.kumulant.math.hash64 so the input has uniform 64-bit entropy; value.hashCode().toLong() only provides 32 bits and skews the estimator on low-cardinality domains.
Exponentially weighted sums and moments over a stream. Each member implements com.eignex.kumulant.core.SeriesStat. Timestamp-based stats discount observations by elapsed time; EWMA stats discount history by cumulative observation weight.
Predictive recurrences over ordered observations. Exponential smoothing exposes forecast(steps) projections and implements com.eignex.kumulant.core.SeriesStat.
Throughput estimators. Every rate result implements com.eignex.kumulant.core.HasRate, so a downstream consumer can pull rate (events per second) or per(duration) through one trait regardless of which underlying estimator produced the snapshot.
Family root for the regression-modality stats and the cross-cutting infrastructure they share. The single-output linear-model family lives in glm, the decision-tree and random-forest family in tree. What sits directly in this package is the small set of stats that don't fit either subfamily, plus the strategy types both rely on.