Namespaces
namespace	detail

Typedefs
using	PerplexityHandle = int32_t

using	BranchMetricsHandle = int32_t

Enumerations
enum class	Base { Nats , Bits }

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

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

float	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	sampling_entropy (const float *candidate_logits, int n_candidates, Base base=Base::Nats)
	Compute sampling-level entropy of candidate distribution.

PerplexityHandle	create_perplexity ()

void	add_surprisal (PerplexityHandle handle, float surprisal)
	Add token surprisal to running average.

float	get_ppl (PerplexityHandle handle)
	Get current perplexity.

int	get_count (PerplexityHandle handle)
	Get number of tokens added to tracker.

void	reset_perplexity (PerplexityHandle handle)
	Reset tracker to initial state (start new sequence)

PerplexityHandle	clone_perplexity (PerplexityHandle handle)

void	free_perplexity (PerplexityHandle handle)
	Free perplexity tracker.

BranchMetricsHandle	create_branch_metrics ()
	Create unified branch metrics tracker.

void	free_branch_metrics (BranchMetricsHandle handle)
	Free branch metrics tracker.

BranchMetricsHandle	clone_branch_metrics (BranchMetricsHandle handle)
	Clone branch metrics tracker (for fork/branching)

void	add_model_surprisal (BranchMetricsHandle handle, float surprisal)
	Add model-level surprisal (from raw logits before filters)

float	get_model_ppl (BranchMetricsHandle handle)
	Get model-level perplexity (from raw logits)

void	add_sampling_surprisal (BranchMetricsHandle handle, float surprisal)
	Add sampling-level surprisal (from filtered distribution)

float	get_sampling_ppl (BranchMetricsHandle handle)
	Get sampling-level perplexity (from filtered distribution)

int	get_model_count (BranchMetricsHandle handle)
	Get number of tokens in model-level tracker.

int	get_sampling_count (BranchMetricsHandle handle)
	Get number of tokens in sampling-level tracker.

Typedef Documentation

◆ BranchMetricsHandle

using lloyal::metrics::BranchMetricsHandle = typedef int32_t

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 427 of file metrics.hpp.

◆ PerplexityHandle

using lloyal::metrics::PerplexityHandle = typedef int32_t

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 44 of file metrics.hpp.

Enumeration Type Documentation

◆ Base

enum class lloyal::metrics::Base

strong

Enumerator
Nats
Bits

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 42 of file metrics.hpp.

Function Documentation

◆ add_model_surprisal()

void lloyal::metrics::add_model_surprisal	(	BranchMetricsHandle	handle,
		float	surprisal
	)

inline

Add model-level surprisal (from raw logits before filters)

Parameters

handle	Branch metrics handle
surprisal	Token surprisal in nats (from model_surprisal)

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 497 of file metrics.hpp.

◆ add_sampling_surprisal()

void lloyal::metrics::add_sampling_surprisal	(	BranchMetricsHandle	handle,
		float	surprisal
	)

inline

Add sampling-level surprisal (from filtered distribution)

Parameters

handle	Branch metrics handle
surprisal	Token surprisal in nats (from sampling_surprisal)

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 528 of file metrics.hpp.

◆ add_surprisal()

void lloyal::metrics::add_surprisal	(	PerplexityHandle	handle,
		float	surprisal
	)

inline

Add token surprisal to running average.

Parameters

handle	Perplexity tracker handle
surprisal	Token surprisal in nats (from model_surprisal)

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 339 of file metrics.hpp.

◆ clone_branch_metrics()

BranchMetricsHandle lloyal::metrics::clone_branch_metrics ( BranchMetricsHandle handle )

inline

Clone branch metrics tracker (for fork/branching)

Creates a new tracker with identical state for both model and sampling levels. Use when forking a branch to preserve metrics history.

Parameters

handle Source branch metrics handle

Returns: New handle with cloned state, or 0 if invalid source

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 481 of file metrics.hpp.

◆ clone_perplexity()

PerplexityHandle lloyal::metrics::clone_perplexity ( PerplexityHandle handle )

inline

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 404 of file metrics.hpp.

◆ create_branch_metrics()

BranchMetricsHandle lloyal::metrics::create_branch_metrics ( )

inline

Create unified branch metrics tracker.

Tracks both model-level (raw logits) and sampling-level (filtered) perplexity in a single handle for atomic clone/free operations.

Returns: Handle to the branch metrics tracker

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 457 of file metrics.hpp.

◆ create_perplexity()

PerplexityHandle lloyal::metrics::create_perplexity ( )

inline

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 327 of file metrics.hpp.

◆ free_branch_metrics()

void lloyal::metrics::free_branch_metrics ( BranchMetricsHandle handle )

inline

Free branch metrics tracker.

Parameters

handle Branch metrics handle

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 468 of file metrics.hpp.

◆ free_perplexity()

void lloyal::metrics::free_perplexity ( PerplexityHandle handle )

inline

Free perplexity tracker.

Parameters

handle Perplexity tracker handle

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 419 of file metrics.hpp.

◆ get_count()

int lloyal::metrics::get_count ( PerplexityHandle handle )

inline

Get number of tokens added to tracker.

Parameters

handle Perplexity tracker handle

Returns: Token count, or 0 if invalid handle

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 369 of file metrics.hpp.

◆ get_model_count()

int lloyal::metrics::get_model_count ( BranchMetricsHandle handle )

inline

Get number of tokens in model-level tracker.

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 556 of file metrics.hpp.

◆ get_model_ppl()

float lloyal::metrics::get_model_ppl ( BranchMetricsHandle handle )

inline

Get model-level perplexity (from raw logits)

Parameters

handle Branch metrics handle

Returns: exp(average surprisal), Infinity if no samples

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 512 of file metrics.hpp.

◆ get_ppl()

float lloyal::metrics::get_ppl ( PerplexityHandle handle )

inline

Get current perplexity.

Parameters

handle Perplexity tracker handle

Returns: exp(average surprisal), Infinity if no samples

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 354 of file metrics.hpp.

◆ get_sampling_count()

int lloyal::metrics::get_sampling_count ( BranchMetricsHandle handle )

inline

Get number of tokens in sampling-level tracker.

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 566 of file metrics.hpp.

◆ get_sampling_ppl()

float lloyal::metrics::get_sampling_ppl ( BranchMetricsHandle handle )

inline

Get sampling-level perplexity (from filtered distribution)

Parameters

handle Branch metrics handle

Returns: exp(average surprisal), Infinity if no samples

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 543 of file metrics.hpp.

◆ model_entropy()

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

inline

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 180 of file metrics.hpp.

◆ model_surprisal()

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

inline

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 131 of file metrics.hpp.

◆ reset_perplexity()

void lloyal::metrics::reset_perplexity ( PerplexityHandle handle )

inline

Reset tracker to initial state (start new sequence)

Parameters

handle Perplexity tracker handle

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 381 of file metrics.hpp.

◆ sampling_entropy()

float lloyal::metrics::sampling_entropy	(	const float *	candidate_logits,
		int	n_candidates,
		Base	base = `Base::Nats`
	)

inline

Compute sampling-level entropy of candidate distribution.

Measures uncertainty within the filtered candidate set (after top-k/p/temperature). Use to monitor distribution health after grammar masks or constraints.

Parameters

candidate_logits	Logits of candidate tokens (post-filter)
n_candidates	Number of candidates
base	Nats (natural log) or Bits (log₂)

Returns: Entropy in nats or bits (≥0, Infinity if invalid)

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 272 of file metrics.hpp.

◆ sampling_surprisal()

float lloyal::metrics::sampling_surprisal	(	const float *	candidate_logits,
		const int32_t *	candidate_ids,
		int	n_candidates,
		int	picked_id,
		Base	base = `Base::Nats`
	)

inline

Compute sampling-level surprisal for picked token.

Measures uncertainty within the filtered candidate set (after top-k/p/temperature). Lower than model surprisal if filters removed low-probability tokens.

Use to monitor runtime hazard when grammar/constraints narrow the distribution.

Parameters

candidate_logits	Logits of candidate tokens (post-filter)
candidate_ids	Token IDs of candidates
n_candidates	Number of candidates
picked_id	Token ID that was sampled
base	Nats (natural log) or Bits (log₂)

Returns: Surprisal in nats or bits (≥0, Infinity if invalid)

Examples: /home/runner/work/liblloyal/liblloyal/include/lloyal/metrics.hpp.

Definition at line 226 of file metrics.hpp.

Namespaces

Typedefs

Enumerations

Functions

Typedef Documentation

◆ BranchMetricsHandle

◆ PerplexityHandle

Enumeration Type Documentation

◆ Base

Function Documentation

◆ add_model_surprisal()

◆ add_sampling_surprisal()

◆ add_surprisal()

◆ clone_branch_metrics()

◆ clone_perplexity()

◆ create_branch_metrics()

◆ create_perplexity()

◆ free_branch_metrics()

◆ free_perplexity()

◆ get_count()

◆ get_model_count()

◆ get_model_ppl()

◆ get_ppl()

◆ get_sampling_count()

◆ get_sampling_ppl()

◆ model_entropy()

◆ model_surprisal()

◆ reset_perplexity()

◆ sampling_entropy()

◆ sampling_surprisal()