module

sampler

ion7.core.SamplerBuilder

_steps table[] Ordered list of per-sampler specs.

_custom_refs ion7.core.CustomSampler[]? Pinned CustomSampler instances.

ion7.core.Sampler

_chain cdata `llama_sampler*` (chain head, GC-managed).

_custom_refs table? Pinned CustomSampler instances (anchors).

Functions

SamplerBuilder.new SamplerBuilder:greedy SamplerBuilder:dist SamplerBuilder:temperature SamplerBuilder:temp SamplerBuilder:temperature_dynamic SamplerBuilder:temp_dynamic SamplerBuilder:top_k SamplerBuilder:top_p SamplerBuilder:min_p SamplerBuilder:top_n_sigma SamplerBuilder:typical SamplerBuilder:xtc SamplerBuilder:mirostat SamplerBuilder:mirostat_v2 SamplerBuilder:penalties SamplerBuilder:dry SamplerBuilder:grammar SamplerBuilder:grammar_lazy SamplerBuilder:logit_bias SamplerBuilder:adaptive_p SamplerBuilder:custom SamplerBuilder:infill SamplerBuilder:reasoning_budget SamplerBuilder:build Sampler._wrap Sampler:sample Sampler:accept Sampler:reset Sampler:seed Sampler:name Sampler:n Sampler:get Sampler:remove Sampler:clone Sampler:perf Sampler:perf_print Sampler:perf_reset Sampler:free Sampler.chain Sampler.default Sampler.greedy Sampler.creative

SamplerBuilder.new

Start a new chain. Returns a fluent builder ; chain method calls (`:top_k(...)`, `:dist()`, ...) and finalise with `:build()`.

SamplerBuilder.new()

→ ion7.core.SamplerBuilder

SamplerBuilder:greedy

Pick the highest-probability token at every step.

SamplerBuilder:greedy()

→ ion7.core.SamplerBuilder

SamplerBuilder:dist

Sample from the (post-temperature) probability distribution.

SamplerBuilder:dist(seed)

seedinteger?RNG seed (default `0xFFFFFFFF` = random).

→ ion7.core.SamplerBuilder

SamplerBuilder:temperature

Apply a temperature to the logits. `0` = greedy ; `1` = unmodified.

SamplerBuilder:temperature(t)

tnumber

→ ion7.core.SamplerBuilder

SamplerBuilder:temp

Alias : shorter spelling of `:temperature`.

SamplerBuilder:temp(t)

SamplerBuilder:temperature_dynamic

Dynamic temperature : final temperature drawn from `[base-range, base+range]`.

SamplerBuilder:temperature_dynamic(base, range, exponent)

basenumberCentre value.

rangenumberHalf-width.

exponentnumber?Exponent of the distribution (default 1).

→ ion7.core.SamplerBuilder

SamplerBuilder:temp_dynamic

Alias : shorter spelling of `:temperature_dynamic`.

SamplerBuilder:temp_dynamic(base, range, exponent)

SamplerBuilder:top_k

Top-K filtering : keep only the K most probable tokens.

SamplerBuilder:top_k(k)

kinteger

→ ion7.core.SamplerBuilder

SamplerBuilder:top_p

Nucleus (top-P) filtering : keep tokens up to cumulative probability `p`.

SamplerBuilder:top_p(p, min_keep)

pnumberThreshold in `(0, 1]`.

min_keepinteger?Floor (default 1).

→ ion7.core.SamplerBuilder

SamplerBuilder:min_p

Min-P filtering : keep tokens whose probability is at least `p × max_prob`.

SamplerBuilder:min_p(p, min_keep)

pnumberThreshold relative to top token.

min_keepinteger?Floor (default 1).

→ ion7.core.SamplerBuilder

SamplerBuilder:top_n_sigma

Top-N-sigma : keep tokens within `n` standard deviations of the maximum logit. Newer (2025) alternative to top-k / top-p.

SamplerBuilder:top_n_sigma(n)

nnumber

→ ion7.core.SamplerBuilder

SamplerBuilder:typical

Locally-typical sampling : selects tokens whose information content matches the expected entropy of the distribution. More natural output than top-p alone for free-form generation.

SamplerBuilder:typical(p, min_keep)

pnumberTypicality threshold in `(0, 1]`.

min_keepinteger?Floor (default 1).

→ ion7.core.SamplerBuilder

SamplerBuilder:xtc

XTC (Exclude Top Choices) : with probability `probability`, drop candidates above `threshold` to encourage diversity.

SamplerBuilder:xtc(probability, threshold, min_keep, seed)

probabilitynumber

thresholdnumberLogit threshold for exclusion.

min_keepinteger?

seedinteger?

→ ion7.core.SamplerBuilder

SamplerBuilder:mirostat

Mirostat v1 : adaptive sampling that targets a constant entropy.

SamplerBuilder:mirostat(n_vocab, tau, eta, m, seed)

n_vocabintegerVocabulary size.

taunumber?Target entropy (default 5).

etanumber?Learning rate (default 0.1).

minteger?Mirostat M (default 100).

seedinteger?

→ ion7.core.SamplerBuilder

SamplerBuilder:mirostat_v2

Mirostat v2 : simpler than v1, no M parameter.

SamplerBuilder:mirostat_v2(tau, eta, seed)

taunumber?(default 5).

etanumber?(default 0.1).

seedinteger?

→ ion7.core.SamplerBuilder

SamplerBuilder:penalties

Repetition / frequency / presence penalties.

SamplerBuilder:penalties(last_n, repeat_penalty, freq_penalty, present_penalty)

last_ninteger?Window in tokens (default 64).

repeat_penaltynumber?> 1 reduces repeats (default 1).

freq_penaltynumber?Per-token frequency penalty.

present_penaltynumber?Presence penalty.

→ ion7.core.SamplerBuilder

SamplerBuilder:dry

DRY (Don't Repeat Yourself) repetition sampler.

SamplerBuilder:dry(opts, vocab, n_ctx_train)

optstable?`{ multiplier, base, allowed_length, penalty_last_n, seq_breakers }`.

vocabcdata`llama_vocab*` (required by llama.cpp).

n_ctx_trainintegerTraining context size (used for sizing).

→ ion7.core.SamplerBuilder

SamplerBuilder:grammar

Constrain output to a GBNF grammar.

SamplerBuilder:grammar(gbnf, root, vocab)

gbnfstringGBNF grammar source.

rootstring?Root rule name (default `"root"`).

vocabcdata|table`llama_vocab*` or a `Vocab` instance.

→ ion7.core.SamplerBuilder

SamplerBuilder:grammar_lazy

Lazy grammar : the grammar only kicks in once one of the trigger conditions is met. Useful for "free-form prose, then JSON when the model emits `{`" workflows (CRANE-style).

SamplerBuilder:grammar_lazy(gbnf, root, vocab, trigger_words, trigger_tokens, trigger_patterns)

SamplerBuilder:logit_bias

Logit bias : `{ [token_id] = delta_logit, ... }`.

SamplerBuilder:logit_bias(biases)

SamplerBuilder:adaptive_p

Adaptive-p sampler : exponentially-decayed probability threshold.

SamplerBuilder:adaptive_p(target, decay, seed)

SamplerBuilder:custom

Plug a Lua-implemented `CustomSampler` into the chain. The builder pins the wrapper so its trampolines outlive the chain.

SamplerBuilder:custom(cs)

SamplerBuilder:infill

Fill-in-the-Middle sampler. Requires a `vocab` cdata or `Vocab`.

SamplerBuilder:infill(vocab)

SamplerBuilder:reasoning_budget

Reasoning-budget sampler : caps the token count inside `...` blocks. MUST be inserted FIRST in the chain. Routed through the libcommon bridge.

SamplerBuilder:reasoning_budget(model, n_budget)

modelcdata|table`llama_model*` or a `Model` instance.

n_budgetintegerMax tokens inside the block (default 512).

→ ion7.core.SamplerBuilder

SamplerBuilder:build

Materialise the chain into a `Sampler` instance ready to use.

SamplerBuilder:build()

→ ion7.core.Sampler

raises — When any sampler init returns NULL.

Sampler._wrap

Internal : wrap a raw chain pointer into a Sampler instance.

Sampler._wrap(chain, custom_refs)

Sampler:sample

Sample the next token from the logits at position `idx`. When called on a CHAIN (the typical case), `llama_sampler_sample` internally calls `llama_sampler_accept` on every step. Do NOT call `Sampler:accept(token)` separately afterwards — that would be a double-accept and would corrupt grammar-state and DRY history.

Sampler:sample(ctx, idx)

ctxcdata`llama_context*`.

idxintegerLogit position (`-1` for the last decoded token).

→ integerSampled token id.

Sampler:accept

Manually notify the chain that a token was accepted. Only useful for sub-samplers obtained via `Sampler:get(i)` ; not needed when you call `:sample` on the chain itself.

Sampler:accept(token)

Sampler:reset

Reset every sub-sampler's state (penalty history, mirostat, grammar).

Sampler:reset()

Sampler:seed

Sampler:seed()

→ integerCurrent RNG seed of the chain.

Sampler:name

Sampler:name()

→ stringSampler name string (top-level chain only).

Sampler:n

Sampler:n()

→ integerNumber of sub-samplers in the chain.

Sampler:get

Get the sub-sampler at index `i`. Returned handle is NOT GC-managed (the chain owns it).

Sampler:get(i)

iinteger0-based.

→ ion7.core.Sampler|nil

Sampler:remove

Remove the sub-sampler at index `i` and return it. Caller takes ownership — the returned Sampler is NOT GC-managed.

Sampler:remove(i)

Sampler:clone

Deep-clone the chain. The clone is independently GC-managed.

Sampler:clone()

→ ion7.core.Sampler

Sampler:perf

Read sampler perf counters into a Lua table.

Sampler:perf()

→ table{ t_sample_ms, n_sample }

Sampler:perf_print

Print sampler perf to stderr.

Sampler:perf_print()

Sampler:perf_reset

Reset sampler perf counters.

Sampler:perf_reset()

Sampler:free

Free the chain immediately. Idempotent. Disarms `ffi.gc` so the GC does not double-free later.

Sampler:free()

Sampler.chain

Entry point of the fluent API.

Sampler.chain()

→ ion7.core.SamplerBuilder

Sampler.default

Pre-built balanced sampler : penalties + top-k 40 + top-p 0.95 + min-p 0.05 + temp 0.8 + dist. Suitable for most chat workloads.

Sampler.default()

→ ion7.core.Sampler

Sampler.greedy

Pure greedy sampler. Deterministic, ideal for grammar-constrained structured output where any randomness would break parsing.

Sampler.greedy()

→ ion7.core.Sampler

Sampler.creative

More adventurous defaults : higher temp, mild repetition control.

Sampler.creative()

→ ion7.core.Sampler