Trait SamplingBackend 

pub trait SamplingBackend {
    type Logits: Clone;
    type Token: Clone;
    type RandomState;
    type Context: ?Sized;
    type Error;

    // Required methods
    fn error(message: String) -> Self::Error;
    fn validate_token(
        token: &Self::Token,
        domain: TokenDomain,
        context: &Self::Context,
    ) -> Result<Self::Token, Self::Error>;
    fn scale_temperature(
        logits: &Self::Logits,
        temperature: f32,
        context: &Self::Context,
    ) -> Result<Self::Logits, Self::Error>;
    fn apply_penalties(
        logits: &Self::Logits,
        history: &[u32],
        penalties: PenaltyConfig,
        context: &Self::Context,
    ) -> Result<Self::Logits, Self::Error>;
    fn apply_top_k(
        logits: Self::Logits,
        top_k: i32,
        context: &Self::Context,
    ) -> Result<Self::Logits, Self::Error>;
    fn apply_top_p(
        logits: Self::Logits,
        top_p: f32,
        context: &Self::Context,
    ) -> Result<Self::Logits, Self::Error>;
    fn apply_min_p(
        logits: Self::Logits,
        min_p: f32,
        context: &Self::Context,
    ) -> Result<Self::Logits, Self::Error>;
    fn apply_token_filter(
        logits: &Self::Logits,
        filter: &TokenFilter,
        context: &Self::Context,
    ) -> Result<Self::Logits, Self::Error>;
    fn apply_mirostat(
        logits: &Self::Logits,
        history: &[u32],
        penalties: PenaltyConfig,
        temperature: f32,
        mu: f32,
        context: &Self::Context,
    ) -> Result<Self::Logits, Self::Error>;
    fn sample_raw(
        logits: &Self::Logits,
        temperature: f32,
        random: Option<&mut Self::RandomState>,
        context: &Self::Context,
    ) -> Result<Self::Token, Self::Error>;
    fn sample_processed(
        logits: &Self::Logits,
        temperature: f32,
        random: Option<&mut Self::RandomState>,
        context: &Self::Context,
    ) -> Result<Self::Token, Self::Error>;
    fn token_id(
        token: &Self::Token,
        context: &Self::Context,
    ) -> Result<u32, Self::Error>;
    fn token_probability(
        logits: &Self::Logits,
        token: u32,
        context: &Self::Context,
    ) -> Result<f32, Self::Error>;
}

Backend primitives required by generic token-sampling policies.

The runtime owns ordering, history, adaptive state, and constraint rollback. Implementations operate directly on native logits and random state without copying values through a neutral tensor representation.

Required Associated Types

type Logits: Clone

Backend-native logits tensor.

type Token: Clone

Backend-native sampled-token tensor.

type RandomState

Backend-native random-key stream.

type Context: ?Sized

Execution context, such as a stream.

type Error

Backend failure.

Required Methods

fn error(message: String) -> Self::Error

Creates a backend error for a portable policy or constraint failure.

fn validate_token( token: &Self::Token, domain: TokenDomain, context: &Self::Context, ) -> Result<Self::Token, Self::Error>

Validates a native token tensor against one architecture-selected domain.

The returned token must retain a backend-native dependency on the range check so lazy backends cannot commit an unchecked forced token.

fn scale_temperature( logits: &Self::Logits, temperature: f32, context: &Self::Context, ) -> Result<Self::Logits, Self::Error>

Scales logits by inverse temperature, preserving the native tensor.

fn apply_penalties( logits: &Self::Logits, history: &[u32], penalties: PenaltyConfig, context: &Self::Context, ) -> Result<Self::Logits, Self::Error>

Applies repetition, frequency, and presence penalties.

fn apply_top_k( logits: Self::Logits, top_k: i32, context: &Self::Context, ) -> Result<Self::Logits, Self::Error>

Masks all but the highest top_k logits. Non-positive values disable it.

fn apply_top_p( logits: Self::Logits, top_p: f32, context: &Self::Context, ) -> Result<Self::Logits, Self::Error>

Applies nucleus filtering while retaining canonical vocabulary order.

fn apply_min_p( logits: Self::Logits, min_p: f32, context: &Self::Context, ) -> Result<Self::Logits, Self::Error>

Applies minimum-relative-probability filtering.

fn apply_token_filter( logits: &Self::Logits, filter: &TokenFilter, context: &Self::Context, ) -> Result<Self::Logits, Self::Error>

Masks tokens rejected by a portable vocabulary filter. Explicit masks are closed sets: wider logits must mask the missing IDs, while narrower logits use the executable prefix. Reject an empty intersection before sampling; TokenFilter::allowed_mask_for implements this shared domain policy without backend tensors.

fn apply_mirostat( logits: &Self::Logits, history: &[u32], penalties: PenaltyConfig, temperature: f32, mu: f32, context: &Self::Context, ) -> Result<Self::Logits, Self::Error>

Applies Mirostat’s surprise cutoff after penalties and temperature.

fn sample_raw( logits: &Self::Logits, temperature: f32, random: Option<&mut Self::RandomState>, context: &Self::Context, ) -> Result<Self::Token, Self::Error>

Selects from raw logits, applying temperature for stochastic sampling.

fn sample_processed( logits: &Self::Logits, temperature: f32, random: Option<&mut Self::RandomState>, context: &Self::Context, ) -> Result<Self::Token, Self::Error>

Selects from logits already scaled by the policy.

fn token_id( token: &Self::Token, context: &Self::Context, ) -> Result<u32, Self::Error>

Materializes only the selected scalar token identifier.

fn token_probability( logits: &Self::Logits, token: u32, context: &Self::Context, ) -> Result<f32, Self::Error>

Materializes one committed token probability from processed logits.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors