Distribution Metrics for Test-Time Alignment. More...

#include <algorithm>
#include <cmath>
#include <cstdint>
#include <limits>

Classes
struct	lloyal::metrics::PerplexityState
	Rolling NLL accumulator for perplexity computation. More...

struct	lloyal::metrics::BranchMetricsState
	Unified model + sampling perplexity tracker. More...

Namespaces
namespace	lloyal
	Boundary Tracker Stub for OSS liblloyal.

namespace	lloyal::metrics

namespace	lloyal::metrics::detail

Enumerations
enum class	lloyal::metrics::Base { lloyal::metrics::Nats , lloyal::metrics::Bits }

Functions
float	lloyal::metrics::detail::max_finite (const float *a, int n)
	Find maximum finite value in array Used for log-sum-exp shift to prevent overflow.

float	lloyal::metrics::detail::log_sum_exp (const float *a, int n, float shift)
	Numerically stable log-sum-exp Computes log(Σ exp(aᵢ)) using shift trick to avoid overflow.

float	lloyal::metrics::model_surprisal (const float *logits, int n_vocab, int picked_id, Base base=Base::Nats)

float	lloyal::metrics::model_entropy (const float *logits, int n_vocab, Base base=Base::Nats)

float	lloyal::metrics::sampling_surprisal (const float candidate_logits, const int32_t candidate_ids, int n_candidates, int picked_id, Base base=Base::Nats)
	Compute sampling-level surprisal for picked token.

float	lloyal::metrics::sampling_entropy (const float *candidate_logits, int n_candidates, Base base=Base::Nats)
	Compute sampling-level entropy of candidate distribution.

Variables
constexpr float	lloyal::metrics::detail::LN2 = 0.693147180559945309417232121458176568f

Detailed Description

Distribution Metrics for Test-Time Alignment.

Computes surprisal, entropy, and perplexity from logits (no attention needed). All metrics derive from softmax(logits) with numerically stable log-sum-exp.

Two measurement levels:

Model metrics: Raw logits (before filters) - model's inherent belief
Sampling metrics: Post-filter logits (after top-k/p/temp) - actual distribution sampled

Use cases:

KV eviction gates: High entropy -> trigger retrieval or cache pruning
Adaptive sampling: Collapsed distribution -> widen search
Quality monitoring: Track surprisal/perplexity for confidence estimates
Dashboard signals: Real-time uncertainty visualization

Perplexity tracking is instance-scoped via BranchStore registries — no global static state. See branch.hpp for the handle-based CRUD.

References:

Shannon entropy: https://www.emblaustralia.org/wp-content/uploads/2023/11/information_theory.pdf
Perplexity: https://huggingface.co/docs/transformers/perplexity

Ported from tsampler/metrics.ts - identical algorithms, validated implementation.

Definition in file metrics.hpp.

Classes

Namespaces

Enumerations

Functions

Variables

Detailed Description