Skip to main content

Crate logit_loom

Crate logit_loom 

Source
Expand description

§logit-loom

Safe Rust machinery for composing token-stream transforms and observers.

The crate provides ordered transform pipelines, full or sparse candidate exposure, transactional write-back, panic/error containment, observer fan-out, cooperative cancellation, and mechanical receipts. It does not load a model.

[dependencies]
logit-loom = "=0.2.0"

§Example

Apply a first-party token bias to an in-memory vocabulary:

use logit_loom::{
    CandidateMode, Digest, Pipeline, Stage, TokenBias, TokenId, TransformSpec,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let target = TokenId::new(42)?;
    let transform = TokenBias::new([(target, 1.5)])?;
    let specification = TransformSpec::new(
        Digest::of_bytes("my-transform", b"token-42-bias-v1"),
        CandidateMode::FullVocabulary,
        16,
    )?;
    let mut pipeline = Pipeline::new(vec![Stage::new(specification, transform)?])?;

    pipeline.begin(&[])?;
    let mut logits = vec![0.0; 128];
    pipeline.apply_to_vocabulary(0, &[], &mut logits)?;

    assert_eq!(logits[42].to_bits(), 1.5_f32.to_bits());
    assert_eq!(pipeline.receipt().invocations, 1);
    Ok(())
}

Each call starts with Pipeline::begin. Successful transform invocations use consecutive zero-based steps. A backend calls Pipeline::accept only after the selected token has entered causal state, once for an unmatched successful transform invocation.

§Failure and observation

  • Candidate changes commit only after every stage succeeds.
  • Callback errors and unwinding are contained and retained in receipts.
  • Backend-selected candidate views must be non-empty, bounded, and contain unique token IDs.
  • Observers are polled before sampling and see exact token bytes only after causal admission.

See the workspace overview, getting-started guide, and architecture.

Structs§

ActivationCapturePlanV1
Bounded activation-capture request.
ActivationCaptureReceiptV1
Aggregate evidence for one completed activation capture.
ActivationCaptureRecordV1
One topology-bound captured tensor row.
ActivationInvocationReceiptV1
Evidence for one successful native tensor write-back.
ActivationInvocationRowV1
Evidence for one successful copy-transform-write transaction.
ActivationOperationV1
One ordered, position-scoped activation operation.
ActivationProgramReceiptV1
Aggregate successful accounting for one activation program runtime.
ActivationProgramV1
Ordered activation operations and observation requests.
ActivationStatisticsV1
Deterministic scalar statistics represented by exact f32 bits.
ActivationVectorAccumulatorV1
Deterministic accumulator for sparse activation samples.
ActivationVectorBankV1
Topology-bound sparse activation vectors.
ActivationVectorProvenanceV1
Mechanical provenance for vector construction.
ActivationVectorRowV1
One canonical sparse vector row.
ActivationVectorSampleV1
One caller-ordered, content-bound sparse activation sample.
AudioPrefillPlanV1
Exact, model-free contract for one audio projector prefill.
AudioPrefillReceiptV1
Content-free terminal accounting for one projected audio prefill.
ByteFeedbackReceiptV1
Complete exact-byte feedback execution for one projection attempt.
ByteFeedbackSpecV1
Exact byte-feedback implementation and resource bounds.
ByteFeedbackStepReceiptV1
Exact symbolic decision before one native sampling operation.
CallbackFailure
Complete error or panic isolated at a callback boundary.
CancellationToken
Cloneable one-shot cooperative cancellation signal.
CausalPositionRangeV1
Inclusive causal-position interval.
CheckpointReceipt
Serializable compatibility metadata for one backend-owned causal checkpoint.
ControlVectorSpec
One in-memory control-vector application.
Digest
A domain-separated BLAKE3 digest encoded as 64 lowercase hexadecimal bytes.
DrySampler
Don’t Repeat Yourself sampler configuration.
GenerationPlan
Complete bounded generation mechanics independent of prompt semantics.
GenerationPlanV2
Version-two generation mechanics with explicit eager or lazy grammar.
GenerationReceipt
Mechanical receipt for one bounded generation call.
Grammar
An eager llama.cpp GBNF grammar.
GrammarPlanV2
Version-two eager or lazy llama.cpp GBNF grammar.
LogitBias
One additive token-logit bias.
LoraSpec
One model-compatible LoRA adapter application.
MirostatSampler
Stateful Mirostat terminal sampler configuration.
ObservedToken
One token already admitted to backend causal state.
ObserverError
Error returned by a generated-token observer.
ObserverReceipt
Mechanical accounting for one generated-token observer.
ObserverSet
Ordered observer fan-out behind one backend callback point.
Pipeline
Ordered, call-scoped transform pipeline.
PipelineReceipt
Aggregate accounting for an ordered transform pipeline.
PipelineSpec
Ordered transform contracts sharing one candidate exposure.
PrefillMonitor
Panic-containing wrapper around one controlled-prefill observer.
PrefillObserverError
Error returned by a prefill observer.
PrefillProgress
Progress at one complete text-prefill boundary.
PrefillReceipt
Mechanical accounting for controlled prefill.
RankBias
Adds a finite value to one dynamically ranked candidate.
RepetitionSampler
Stateful repetition, frequency, and presence penalties.
SamplingPlan
Native sampler configuration.
SpeculationBoundaryReceiptV1
Target-authoritative accounting for one completed proposal boundary.
SpeculationPlanV1
Complete backend-neutral configuration for one speculative text operation.
SpeculationReceiptV1
Aggregate proposal and target-acceptance accounting.
SpeculationTelemetryResolutionV1
Final disposition of one provisional activation telemetry record.
SpeculativeCheckpointReceiptV1
Serializable evidence for one quiescent speculative checkpoint envelope.
Stage
One identified implementation in an ordered pipeline.
StageReceipt
Mechanical accounting for one transform stage.
SteeringReceipt
Mechanical receipt for one steering lifecycle transition.
StructuredAttemptReceiptV1
One generated, incrementally constrained, and validated projection attempt.
StructuredCompilationReceiptV1
Evidence that an identified compiler produced one complete projection plan.
StructuredMechanicIdentityV1
Content identities for one installed compiler, validator, or feedback implementation and its exact configuration.
StructuredProjectionPlanV1
Complete compiled mechanics for one structured projection controller.
StructuredProjectionReceiptV1
Terminal evidence for a projection selected after zero or more explicit cancelled/rejected attempts.
StructuredValidationReceiptV1
Content-free evidence from one installed authoritative validator.
TextMechanicsCheckpointReceiptV2
Exact ordinary-context state captured at an aggregate operation boundary.
TextMechanicsCleanupReceiptV2
Resource-release and quiescence evidence at aggregate operation completion.
TextMechanicsPlanV1
Complete backend-neutral mechanics for one bounded text operation.
TextMechanicsPlanV2
Aggregate text mechanics with topology-bound activation and speculation.
TextMechanicsReceiptV1
Content-free terminal evidence for TextMechanicsPlanV1.
TextMechanicsReceiptV2
Content-free terminal evidence for TextMechanicsPlanV2.
TextModelTopologyV1
Backend-neutral, content-bound model topology.
TokenBias
Adds finite per-token values to candidates present in the current view.
TokenId
A non-negative model-tokenizer identifier.
TransformContext
Borrowed state supplied to one Rust logit-transform invocation.
TransformError
Error returned by a user-defined logit transform.
TransformSpec
One content-identified transform contract.

Enums§

ActivationCapturePositionsV1
Causal positions retained by one activation capture.
ActivationCaptureRetentionV1
Data retained for each selected tensor row.
ActivationCapturedDataV1
Retained data for one captured tensor row.
ActivationOperatorV1
Built-in transactional tensor operator.
ActivationPhaseV1
Decode phase at which one activation operation executes.
ActivationPositionScopeV1
Causal positions selected by one activation operation.
ActivationTelemetryDispositionV1
Causal status of telemetry created during target or draft evaluation.
ActivationVectorNormalizationV1
Per-row vector normalization contract.
ActivationVectorOperationV1
Content-free vector construction performed by an accumulator.
CallbackPhase
Callback phase that produced a contained failure.
CandidateMode
Candidate-logit exposure presented to every stage in a pipeline.
ControlFlow
Cooperative action returned at a documented safe execution boundary.
CoreError
Failures raised while constructing or validating public contracts.
GenerationFinish
Why one bounded generation call stopped.
GrammarActivationV2
Activation policy for a version-two native grammar.
MirostatVersion
Native Mirostat algorithm version.
PipelineError
Failure while validating or executing an ordered pipeline.
PrefillFinish
Current or terminal disposition of one controlled prefill operation.
SpeculationActivationPolicyV1
Explicit target and draft activation-program selection.
SteeringAction
Lifecycle action recorded at the Rust/native boundary.
SteeringKind
Session steering resource kind.
StructuredAttemptDispositionV1
Effect of one caller-explicit projection attempt.
StructuredValidationStatusV1
Authoritative post-generation validation result.
TextSpeculativeMechanismV1
Speculative mechanisms a loaded text topology can report.
TextTensorElementTypeV1
Tensor element representation expected at a selected graph site.
TextTensorSiteFamilyV1
Stable family shared by compatible activation vector rows and tensor sites.
TextTensorSiteV1
Exact graph tensor selected for capture or mutation.

Constants§

MAX_ACTIVATION_CAPTURE_POSITIONS
Maximum causal positions selected by one capture.
MAX_ACTIVATION_ELEMENTS
Maximum f32 elements copied or retained by one activation operation.
MAX_ACTIVATION_INVOCATION_RECEIPTS
Maximum successful tensor transactions retained in one program receipt.
MAX_ACTIVATION_OBSERVATIONS
Maximum capture-plan observations named by one program.
MAX_ACTIVATION_OPERATIONS
Maximum ordered activation operations in one program.
MAX_ACTIVATION_POSITION_RANGES
Maximum inclusive causal ranges selected by one contract.
MAX_ACTIVATION_RETAINED_BYTES
Maximum retained activation bytes declared by one capture.
MAX_ACTIVATION_ROW_SEQUENCES
Maximum sequence identifiers attached to one logical tensor row.
MAX_ACTIVATION_SITES
Maximum exact tensor sites selected by one capture or operation.
MAX_ACTIVATION_TRANSACTION_ROWS
Maximum logical rows represented by one tensor transaction.
MAX_ACTIVATION_VECTOR_INPUTS
Maximum input artifacts represented by vector provenance.
MAX_ACTIVATION_VECTOR_ROWS
Maximum sparse vector rows in one bank.
MAX_AUDIO_FRAMES
Largest number of mono frames accepted by one audio-prefill plan.
MAX_AUDIO_SAMPLE_RATE_HZ
Largest projector-declared sampling rate accepted by this contract.
MAX_DRY_SEQUENCE_BREAKERS
Maximum exact sequence breakers accepted by one DRY sampler.
MAX_DRY_SEQUENCE_BREAKER_BYTES
Maximum UTF-8 bytes accepted in one DRY sequence breaker.
MAX_GRAMMAR_ROOT_BYTES
Maximum UTF-8 bytes accepted in an eager grammar root name.
MAX_GRAMMAR_SOURCE_BYTES
Maximum UTF-8 bytes accepted in an eager grammar source.
MAX_LAZY_GRAMMAR_TRIGGER_BYTES
Maximum aggregate UTF-8 bytes accepted across lazy-grammar trigger patterns.
MAX_LAZY_GRAMMAR_TRIGGER_PATTERNS
Maximum trigger patterns accepted by one lazy grammar.
MAX_LAZY_GRAMMAR_TRIGGER_PATTERN_BYTES
Maximum UTF-8 bytes accepted in one lazy-grammar trigger pattern.
MAX_LAZY_GRAMMAR_TRIGGER_TOKENS
Maximum trigger tokens accepted by one lazy grammar.
MAX_LOGIT_BIASES
Maximum additive token biases accepted by one generation plan.
MAX_OBSERVERS
Maximum observers sharing one ordered fan-out.
MAX_PIPELINE_STAGES
Maximum stages in one ordered transform pipeline.
MAX_SPARSE_CANDIDATES
Maximum sparse candidates exposed to one transform call.
MAX_SPECULATION_BOUNDARIES
Maximum completed proposal boundaries retained in one aggregate receipt.
MAX_SPECULATION_SEQUENCES
Maximum sequence slots declared by one speculative plan.
MAX_SPECULATION_STATE_BYTES
Maximum opaque speculative implementation-state bytes.
MAX_SPECULATION_TELEMETRY_RESOLUTIONS
Maximum activation telemetry resolutions retained at one proposal boundary.
MAX_SPECULATIVE_TOKENS
Maximum speculative tokens requested from one draft boundary.
MAX_STOP_SEQUENCES
Maximum exact byte stop sequences accepted by one generation plan.
MAX_STOP_SEQUENCE_BYTES
Maximum bytes accepted in one exact stop sequence.
MAX_STRUCTURED_ATTEMPTS
Maximum caller-explicit attempts retained by one projection controller.
MAX_STRUCTURED_CANDIDATES
Maximum model vocabulary accepted by structured byte feedback.
MAX_STRUCTURED_OUTPUT_BYTES
Maximum generated bytes accepted by one feedback implementation.
MAX_STRUCTURED_SCOPE_BYTES
Maximum UTF-8 bytes in one caller-defined projection scope.
MAX_STRUCTURED_STEPS
Maximum generated-token decisions accepted by one feedback implementation.
MAX_TEXT_MECHANICS_CAPTURES
Maximum activation-capture plans bound into one aggregate operation.
MAX_TEXT_MECHANICS_LORAS
Maximum LoRA applications bound into one text-mechanics plan.
MAX_TEXT_MODEL_EXPERTS
Maximum experts represented by one topology contract.
MAX_TEXT_MODEL_LAYERS
Maximum transformer layers represented by one topology contract.
MAX_TEXT_TENSOR_NAME_BYTES
Maximum UTF-8 bytes in a backend-profile tensor name.
MAX_TEXT_TENSOR_ROW_ELEMENTS
Maximum elements in one reported model row.

Traits§

LogitTransform
Safe, synchronous implementation of one per-step logit transformation.
Observer
Safe synchronous observer for generated-token boundaries.
PrefillObserver
Safe synchronous observer for complete prefill chunks.

Functions§

activation_f32_row_identity
Returns the canonical identity of one bounded finite activation f32 row.
structured_output_digest
Returns the stable identity used for exact generated projection bytes.
structured_tokens_digest
Returns the stable identity used for a complete ordered token-ID sequence.