kumulant API reference

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

Contextual bandits: each round comes with a feature vector, and the reward depends on both the chosen arm and the context. Three families, covering linear / non-linear / non-parametric reward models plus the adversarial-expert case.

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.

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.

Distribution sampling and stream-hash functions consumed by the rest of the library. The vector / matrix primitives and BLAS-style linear algebra live in the separate koblas library (com.eignex.koblas); this package holds only the sampling and hashing helpers.

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.

The wire-portable weighting strategies for the time-decay and smoothing stats. A DecayWeightingSpec is the serializable counterpart of the runtime weighting in com.eignex.kumulant.stat.decay: it says how fast old observations should fade, and inflates to the live form when the stat is materialized.

The serializable expression AST behind the lambda-bound 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. They are the spec-side mirror of the live operators in com.eignex.kumulant.operation: where the live form wraps a running stat, the form here wraps its spec, and the two produce the same behaviour once materialized.

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.

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

Online anomaly detectors. All three primitives produce a score(x) method on their result so the same downstream pipeline can consume "how anomalous is this observation?" regardless of which detector generated it.

Probability calibration: diagnosing when a classifier's predicted probabilities are out of step with the empirical positive rate, and two complementary mappings that fix it.

Approximate distinct-count estimators. Both entries take a stream of opaque Long keys (com.eignex.kumulant.core.DiscreteStat) and answer "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 / com.eignex.kumulant.math.Hasher64 so the input has uniform 64-bit entropy; value.hashCode().toLong() only provides 32 bits and skews the estimators on low-cardinality domains.

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.

Time-weighted moments. Each observation enters the accumulator with a weight that shrinks toward zero with age, so older observations contribute less. Two parallel sub-families: timestamp-based decay (the Decaying* stats) and step-based EWMA (the Ewma* stats).

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

Predictive recurrences with multi-cell state. Their results expose forecast(steps) projections, distinguishing them from the decay family's running-moment shape.

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.

Throughput estimators. All three implement 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.

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.

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.

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

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

Exact running aggregates over a stream of scalars. Memory is constant in the stream length; updates are O(1); every entry merges cleanly across parallel workers via Chan-style parallel formulas or commuting cell arithmetic.