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§
- Activation
Capture Plan V1 - Bounded activation-capture request.
- Activation
Capture Receipt V1 - Aggregate evidence for one completed activation capture.
- Activation
Capture Record V1 - One topology-bound captured tensor row.
- Activation
Invocation Receipt V1 - Evidence for one successful native tensor write-back.
- Activation
Invocation RowV1 - Evidence for one successful copy-transform-write transaction.
- Activation
Operation V1 - One ordered, position-scoped activation operation.
- Activation
Program Receipt V1 - Aggregate successful accounting for one activation program runtime.
- Activation
Program V1 - Ordered activation operations and observation requests.
- Activation
Statistics V1 - Deterministic scalar statistics represented by exact
f32bits. - Activation
Vector Accumulator V1 - Deterministic accumulator for sparse activation samples.
- Activation
Vector Bank V1 - Topology-bound sparse activation vectors.
- Activation
Vector Provenance V1 - Mechanical provenance for vector construction.
- Activation
Vector RowV1 - One canonical sparse vector row.
- Activation
Vector Sample V1 - One caller-ordered, content-bound sparse activation sample.
- Audio
Prefill Plan V1 - Exact, model-free contract for one audio projector prefill.
- Audio
Prefill Receipt V1 - Content-free terminal accounting for one projected audio prefill.
- Byte
Feedback Receipt V1 - Complete exact-byte feedback execution for one projection attempt.
- Byte
Feedback Spec V1 - Exact byte-feedback implementation and resource bounds.
- Byte
Feedback Step Receipt V1 - Exact symbolic decision before one native sampling operation.
- Callback
Failure - Complete error or panic isolated at a callback boundary.
- Cancellation
Token - Cloneable one-shot cooperative cancellation signal.
- Causal
Position Range V1 - Inclusive causal-position interval.
- Checkpoint
Receipt - Serializable compatibility metadata for one backend-owned causal checkpoint.
- Control
Vector Spec - 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.
- Generation
Plan - Complete bounded generation mechanics independent of prompt semantics.
- Generation
Plan V2 - Version-two generation mechanics with explicit eager or lazy grammar.
- Generation
Receipt - Mechanical receipt for one bounded generation call.
- Grammar
- An eager llama.cpp GBNF grammar.
- Grammar
Plan V2 - Version-two eager or lazy llama.cpp GBNF grammar.
- Logit
Bias - One additive token-logit bias.
- Lora
Spec - One model-compatible
LoRAadapter application. - Mirostat
Sampler - Stateful Mirostat terminal sampler configuration.
- Observed
Token - One token already admitted to backend causal state.
- Observer
Error - Error returned by a generated-token observer.
- Observer
Receipt - Mechanical accounting for one generated-token observer.
- Observer
Set - Ordered observer fan-out behind one backend callback point.
- Pipeline
- Ordered, call-scoped transform pipeline.
- Pipeline
Receipt - Aggregate accounting for an ordered transform pipeline.
- Pipeline
Spec - Ordered transform contracts sharing one candidate exposure.
- Prefill
Monitor - Panic-containing wrapper around one controlled-prefill observer.
- Prefill
Observer Error - Error returned by a prefill observer.
- Prefill
Progress - Progress at one complete text-prefill boundary.
- Prefill
Receipt - Mechanical accounting for controlled prefill.
- Rank
Bias - Adds a finite value to one dynamically ranked candidate.
- Repetition
Sampler - Stateful repetition, frequency, and presence penalties.
- Sampling
Plan - Native sampler configuration.
- Speculation
Boundary Receipt V1 - Target-authoritative accounting for one completed proposal boundary.
- Speculation
Plan V1 - Complete backend-neutral configuration for one speculative text operation.
- Speculation
Receipt V1 - Aggregate proposal and target-acceptance accounting.
- Speculation
Telemetry Resolution V1 - Final disposition of one provisional activation telemetry record.
- Speculative
Checkpoint Receipt V1 - Serializable evidence for one quiescent speculative checkpoint envelope.
- Stage
- One identified implementation in an ordered pipeline.
- Stage
Receipt - Mechanical accounting for one transform stage.
- Steering
Receipt - Mechanical receipt for one steering lifecycle transition.
- Structured
Attempt Receipt V1 - One generated, incrementally constrained, and validated projection attempt.
- Structured
Compilation Receipt V1 - Evidence that an identified compiler produced one complete projection plan.
- Structured
Mechanic Identity V1 - Content identities for one installed compiler, validator, or feedback implementation and its exact configuration.
- Structured
Projection Plan V1 - Complete compiled mechanics for one structured projection controller.
- Structured
Projection Receipt V1 - Terminal evidence for a projection selected after zero or more explicit cancelled/rejected attempts.
- Structured
Validation Receipt V1 - Content-free evidence from one installed authoritative validator.
- Text
Mechanics Checkpoint Receipt V2 - Exact ordinary-context state captured at an aggregate operation boundary.
- Text
Mechanics Cleanup Receipt V2 - Resource-release and quiescence evidence at aggregate operation completion.
- Text
Mechanics Plan V1 - Complete backend-neutral mechanics for one bounded text operation.
- Text
Mechanics Plan V2 - Aggregate text mechanics with topology-bound activation and speculation.
- Text
Mechanics Receipt V1 - Content-free terminal evidence for
TextMechanicsPlanV1. - Text
Mechanics Receipt V2 - Content-free terminal evidence for
TextMechanicsPlanV2. - Text
Model Topology V1 - Backend-neutral, content-bound model topology.
- Token
Bias - Adds finite per-token values to candidates present in the current view.
- TokenId
- A non-negative model-tokenizer identifier.
- Transform
Context - Borrowed state supplied to one Rust logit-transform invocation.
- Transform
Error - Error returned by a user-defined logit transform.
- Transform
Spec - One content-identified transform contract.
Enums§
- Activation
Capture Positions V1 - Causal positions retained by one activation capture.
- Activation
Capture Retention V1 - Data retained for each selected tensor row.
- Activation
Captured Data V1 - Retained data for one captured tensor row.
- Activation
Operator V1 - Built-in transactional tensor operator.
- Activation
Phase V1 - Decode phase at which one activation operation executes.
- Activation
Position Scope V1 - Causal positions selected by one activation operation.
- Activation
Telemetry Disposition V1 - Causal status of telemetry created during target or draft evaluation.
- Activation
Vector Normalization V1 - Per-row vector normalization contract.
- Activation
Vector Operation V1 - Content-free vector construction performed by an accumulator.
- Callback
Phase - Callback phase that produced a contained failure.
- Candidate
Mode - Candidate-logit exposure presented to every stage in a pipeline.
- Control
Flow - Cooperative action returned at a documented safe execution boundary.
- Core
Error - Failures raised while constructing or validating public contracts.
- Generation
Finish - Why one bounded generation call stopped.
- Grammar
Activation V2 - Activation policy for a version-two native grammar.
- Mirostat
Version - Native Mirostat algorithm version.
- Pipeline
Error - Failure while validating or executing an ordered pipeline.
- Prefill
Finish - Current or terminal disposition of one controlled prefill operation.
- Speculation
Activation Policy V1 - Explicit target and draft activation-program selection.
- Steering
Action - Lifecycle action recorded at the Rust/native boundary.
- Steering
Kind - Session steering resource kind.
- Structured
Attempt Disposition V1 - Effect of one caller-explicit projection attempt.
- Structured
Validation Status V1 - Authoritative post-generation validation result.
- Text
Speculative Mechanism V1 - Speculative mechanisms a loaded text topology can report.
- Text
Tensor Element Type V1 - Tensor element representation expected at a selected graph site.
- Text
Tensor Site Family V1 - Stable family shared by compatible activation vector rows and tensor sites.
- Text
Tensor Site V1 - Exact graph tensor selected for capture or mutation.
Constants§
- MAX_
ACTIVATION_ CAPTURE_ POSITIONS - Maximum causal positions selected by one capture.
- MAX_
ACTIVATION_ ELEMENTS - Maximum
f32elements 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
LoRAapplications 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§
- Logit
Transform - Safe, synchronous implementation of one per-step logit transformation.
- Observer
- Safe synchronous observer for generated-token boundaries.
- Prefill
Observer - Safe synchronous observer for complete prefill chunks.
Functions§
- activation_
f32_ row_ identity - Returns the canonical identity of one bounded finite activation
f32row. - 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.