kumulant

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: Concurrency records 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.0

The 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

Link copied to clipboard
common

Multi-armed and contextual bandits built on the same Stat / Result foundation as the rest of the library.

Link copied to clipboard
common

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.

Link copied to clipboard
common

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.

Link copied to clipboard
common

Foundation types every other package builds on. Everything else in the library imports from here: the modality interfaces, the result hierarchy, the cross-cutting result traits, and the concurrency contract.

Link copied to clipboard
common

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).

Link copied to clipboard
common

The schema layer lets you declare a named, typed bag of stats once and treat it as a single unit: every update fans out to all of them, results read back by typed key, and the declaration itself travels on the wire so another process can stand up the same bag and merge snapshots back.

Link copied to clipboard
common

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.

Link copied to clipboard
common

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.

Link copied to clipboard
common

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.

Link copied to clipboard
common

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.

Link copied to clipboard
common

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.

Link copied to clipboard
common

Concrete accumulators grouped by family. Each family lives in its own subpackage; this page is the navigation index.

Link copied to clipboard
common

Stateless anomaly scores derived from summary and quantile snapshots. Accumulate observations with the underlying stat, then score a query against its result. Both scores increase toward anomalous values; neither helper changes the snapshot.

Link copied to clipboard
common

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.

Link copied to clipboard
common

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.

Link copied to clipboard
common

Drift detectors. Each member tracks a running statistic, applies a configurable threshold, and exposes an alarm flag on its result. The three differ in what they assume about the in-control state and how they decide a shift has occurred.

Link copied to clipboard
common

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.

Link copied to clipboard
common

Stats whose output is discrete-temporal in shape: state transitions, dwell times, last-seen timestamps, level crossings, run lengths. They share the streaming-stats discipline but their results carry counts of state changes and timestamps rather than numeric aggregates.

Link copied to clipboard
common

Predictive recurrences over ordered observations. Exponential smoothing exposes forecast(steps) projections and implements com.eignex.kumulant.core.SeriesStat.

Link copied to clipboard
common

Bounded-memory quantile estimators and histograms. Every entry trades a different precision-versus-cost knob: relative error guarantees, fixed-precision over a known range, reservoir sampling for raw values back, or constant memory at the cost of accuracy.

Link copied to clipboard
common

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.

Link copied to clipboard
common

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.

Link copied to clipboard
common

Generalised linear models; the linear-predictor-plus-link family. Every model in this package shares the shape eta = bias + x . weights followed by mu = link.invMean(eta); they differ in how the posterior over weights is maintained.

Link copied to clipboard
common

Online VFDT decision trees and random forests, plus the shared machinery they're built on. The package covers both regression (continuous y) and classification (y in [0, numClasses)) under one consistent shape.

Link copied to clipboard
common

Online evaluation metrics. Inputs are paired (prediction, truth) observations (or richer shapes for distributional metrics) and outputs are accuracy / discrimination / calibration / distributional summaries.

Link copied to clipboard
common

Structural queries on a stream that aren't shaped like a cardinality or a quantile. Three members; each answers a different question.

Link copied to clipboard
common

Running aggregates over scalar streams, from exact sums and moments to approximate robust dispersion estimates. Memory is bounded in the stream length; update and read costs depend on the stat. Each entry supports merging snapshots from parallel workers.

Link copied to clipboard
common