ScriptedEngine class

An engine that answers each generation with the next string of outputs, in chunkSize-character deltas, and records what it was asked.

Unlike a real engine it may be loaded again, also while loaded and after dispose, so one instance can serve several controllers or reloads. Otherwise it keeps the engine rules: operations run in call order, a cancel acts as on a real engine, and dispose cancels the queued and running generations and fails the other queued calls; until the next load, every call throws StateError. Its figures are deterministic: prompt and prefill tokens are prompt.length ~/ 4, decode tokens the number of deltas, times 0; countTokens is text.length ~/ 4. saveState writes the prefix text itself to the file, loadState reads it back.

A generation with no output left fails with ScriptExhausted, which is also reported to the zone of the generate call: the test fails even when the code under test catches every error.

Implemented types

Constructors

ScriptedEngine({String chatTemplate = qwen35ChatTemplate, Map<String, String> metadata = const {}, int chunkSize = 7, bool supportsStatePersistence = true})

Properties

chatTemplate → String
The tokenizer.chat_template of the models it loads.
final
chunkSize → int
Characters per text delta.
final
contextEpoch → int
Counts the calls that change the context: generate, saveState and loadState add 1 when called, before they return, whether they later run, fail or are cancelled. An unchanged value means the context still holds what the caller left there.
no setteroverride
disposes ↔ int
Calls of dispose.
getter/setter pair
failNextLoadState ↔ Object?
Thrown once by the next loadState, wrapped in a StateFileException.
getter/setter pair
gate ↔ Completer<void>?
While set and not completed, a generation waits for it before its first delta (a turn stays running). A cancel ends the wait.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
info → EngineInfo?
The loaded model; null before load completes and after dispose.
no setteroverride
isLoaded → bool
Whether a model is loaded and the engine is not disposed.
no setteroverride
loads ↔ int
Calls of loadState.
getter/setter pair
options → List<GenerationOptions>
The options of every generation, in call order.
final
outputs → List<String>
The raw outputs still to give, one per generation, consumed in order.
final
prompts → List<String>
Every prompt received, in call order.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
saves ↔ int
Calls of saveState.
getter/setter pair
supportsStatePersistence → bool
Whether saveState and loadState work on this runtime.
final
throwAfterDeltas ↔ (int, Object)?
(n, error): the next generation fails with error after n deltas (after all of them when its output has fewer), as a runtime failure does: the handle gets a GenerationException whose cause is error.
getter/setter pair

Methods

countTokens(String text) → Future<int>
(await tokenize(text)).length.
override
dispose() → Future<void>
Counts the call; then as on a real engine: queued generations end cancelled, other queued calls fail with StateError, the running generation is cancelled. Completes once the running operation has finished.
override
generate(String prompt, [GenerationOptions options = const GenerationOptions()]) → Generation
Queues a generation from the rendered prompt and returns its handle at once. A runtime failure, or no model loaded when its turn comes, fails the handle; only a call after dispose throws (StateError).
override
load(String modelPath, [LoadOptions options = const LoadOptions()]) → Future<EngineInfo>
Loads modelPath. Throws StateError while a model is loaded or loading, ModelLoadException when the runtime cannot load it. A model without a chat template loads (EngineInfo.chatTemplate is then null).
override
loadState(String path) → Future<int>
Restores a state written by saveState; returns the tokens it holds. Failures throw StateFileException.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
saveState(String path, String promptPrefix) → Future<SavedState>
Fills the context with exactly promptPrefix, samples nothing, and writes the state to path. A recurrent state cannot be rewound, so the state ends at the prefix's last token. Failures throw StateFileException.
override
tokenize(String text) → Future<List<int>>
The tokens of text, special tokens added as generate adds them (the vocabulary decides about BOS).
override
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

runtime → const RuntimeInfo
The runtime a ScriptedEngine reports.