Struct RosaPlus 

pub struct RosaPlus { /* private fields */ }

ROSA+ predictive model with optional transactional updates.

Implementations

impl RosaPlus

pub fn new(max_order: i64, use_eot: bool, eot_char: u8, seed: u64) -> Self

Create a new ROSA+ model.

max_order < 0 enables adaptive order selection in predictive scoring.

pub fn train_example(&mut self, s: &[u8])

Train on one byte sequence, optionally appending EOT marker.

pub fn reserve_for_stream(&mut self, additional_bytes: usize)

Reserve append-only buffers for a future byte stream.

This keeps compression-side updates from repeatedly growing the same vectors.

pub fn build_lm(&mut self)

Build the language model from current SAM state.

pub fn build_lm_no_finalize_endpos(&mut self)

Build the language model without mutating SAM endpos.

This is useful when you want to reuse a trained SAM as a stable base state (e.g. universal-prior conditioning) and need cheap checkpoint/restore via truncation.

Note: entropy/cross-entropy estimation does not require endpos finalization.

pub fn build_lm_full_bytes_no_finalize_endpos(&mut self)

Build an LM with a fixed byte alphabet of size 256.

This avoids alphabet growth issues and enables fast incremental updates.

pub fn begin_tx(&mut self) -> RosaTx

Begin a reversible conditional update transaction.

pub fn train_example_tx(&mut self, tx: &mut RosaTx, s: &[u8])

Apply a training example and update LM counts incrementally (byte alphabet must be full 256).

pub fn train_sequence_tx(&mut self, tx: &mut RosaTx, s: &[u8])

Apply a sequential update without inserting a boundary (continuous stream).

pub fn train_sequence(&mut self, s: &[u8])

Apply a sequential byte-stream update without rollback bookkeeping.

pub fn train_byte(&mut self, b: u8)

Apply a single byte sequential update without rollback bookkeeping.

pub fn reset_conditioning_cursor(&mut self)

Reset only the predictive cursor while preserving the trained SAM/LM.

pub fn advance_conditioning_byte(&mut self, b: u8)

Advance only the predictive cursor without mutating fitted counts.

pub fn rollback_tx(&mut self, tx: RosaTx)

Roll back a transaction, restoring the model to the exact state at begin_tx.

pub fn ensure_lm_built_no_finalize_endpos(&mut self)

Ensure the LM is built (without mutating SAM endpos).

pub fn lm_alpha_n(&self) -> usize

Current LM alphabet size (0 if LM not built).

pub fn estimated_size_bytes(&self) -> usize

Approximate in-memory footprint of major model buffers.

pub fn shrink_aux_buffers(&mut self)

Shrink auxiliary scratch buffers to fit current usage.

pub fn fork_from_sam(&self) -> Self

Create a new model that shares the same trained SAM state but resets LM-related buffers.

This is substantially cheaper than cloning the full RosaPlus (which includes LM counts, node tables, and distribution buffers) and is safe for workflows that want to start from a fixed base training text (e.g. a universal prior) and then add candidate-specific text.

pub fn checkpoint(&self) -> RosaCheckpoint

A checkpoint that allows restoring the ROSA model back to a previous trained state by truncating append-only internal buffers.

Intended for workflows that repeatedly evaluate different continuations from the same base training text (e.g. universal-prior conditioned scoring).

pub fn restore(&mut self, ck: &RosaCheckpoint)

Restore the model to a previously captured checkpoint.

This invalidates the LM; callers should rebuild it before scoring.

pub fn generate(&mut self, prompt: &[u8], steps: i32) -> Option<Vec<u8>>

Generate continuation bytes from a prompt.

Returns None if LM is not built yet.

pub fn get_distribution(&mut self, context: &[u8]) -> Vec<(u32, f64)>

Returns the probability distribution for the next symbol given a context. Output: Vec of (codepoint, probability) pairs, sorted by codepoint. Builds the LM if not already built.

pub fn predictive_entropy_rate(&mut self, data: &[u8]) -> f64

Compute the predictive entropy rate (bits per symbol) of the given data.

Uses chunked prequential scoring (train on past chunks, score next chunk).

pub fn entropy_rate_cps(&mut self, cps: &[u32]) -> f64

Predictive entropy rate on codepoint streams.

pub fn cross_entropy(&self, data: &[u8]) -> f64

Cross entropy of byte data under current LM state.

pub fn cross_entropy_cps(&self, data: &[u32]) -> f64

Cross entropy of codepoint data under current LM state.

pub fn marginal_distribution(&self) -> Vec<(u32, f64)>

Returns the marginal (unigram) distribution over the training data. Output: Vec of (codepoint, probability) pairs, sorted by codepoint.

pub fn marginal_entropy(&self) -> f64

Compute the marginal entropy H(X) from the unigram distribution. Returns bits per symbol.

pub fn save(&self, path: &str) -> Result<()>

Persist trained SAM+LM state to disk.

pub fn load(path: &str) -> Result<Self>

Load a previously saved ROSA+ model from disk.

pub fn prob_for_last(&mut self, sym: u32) -> f64

Probability of sym from current SAM cursor (sam.last).

pub fn fill_probs_for_last_bytes(&mut self, out: &mut [f64])

Fill a dense byte-wise probability vector for the current SAM cursor (sam.last).

out must have length at least 256. The output is normalized.

Trait Implementations

impl Clone for RosaPlus

fn clone(&self) -> RosaPlus

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.