livekit-wakeword: runtime-configurable ONNX session options

[pham-tuan-binh]

Before you submit your PR

Make sure the following is true before submitting your PR:

• I have read the contributing guidelines and validated that this PR will be accepted.
• I have read and followed the principles regarding breaking changes, testing, and code quality.

PR description

livekit-wakeword builds every session with a bare Session::builder():

Ok(Session::builder()?.commit_from_memory(bytes)?)

so how much CPU wake word detection uses, and whether the ONNX graph is optimized at
all, are both fixed by the crate. The Python SDK takes a sess_options parameter for
exactly this (livekit-wakeword#73),
which lets a caller run detection as a soft background process:

opts = ort.SessionOptions()
opts.intra_op_num_threads = 1
opts.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL
opts.add_session_config_entry("session.intra_op.allow_spinning", "0")
model = WakeWordModel(models=model_files, sess_options=opts)

This adds the Rust equivalent, supplied at runtime:

let options = SessionOptions {
    intra_threads: Some(1),
    inter_threads: Some(1),
    parallel_execution: Some(false),
    intra_op_spinning: Some(false),
    inter_op_spinning: Some(false),
    ..Default::default()
};
let model = WakeWordModel::with_session_options(&models, 16000, options)?;

SessionOptions is applied to the two bundled feature extraction models, to every
classifier passed to the constructor, and — since it is stored on the model — to any
classifier a later load_model call adds. load_model_with_session_options overrides
it for a single classifier, matching Python's per-call sess_options.

Why the crate's own type rather than ort::SessionBuilder

ort is at 2.0.0-rc.11, so exposing its types would make every rc bump a breaking
change for consumers of this crate, and the type buys little here — see below.

Unsupported options are skipped, not fatal

ort-tract, used on every target except aarch64 Windows, implements only
SetSessionGraphOptimizationLevel (its SessionOptions is literally
{ perform_optimizations: bool }); every other session option falls through to
ort-sys' stub API and returns ORT_NOT_IMPLEMENTED. Applied naively, the Python
snippet above would fail to build a session at all on the default backend. Each
option other than the optimization level is therefore applied best-effort, and a
NotImplemented result leaves the builder unchanged. That is not just leniency:
tract runs single-threaded and never spin-waits, so intra_threads: Some(1) and
intra_op_spinning: Some(false) already describe what it does — the request is
satisfied, just not expressible.

Default is Level3

SessionOptions::default() requests OptimizationLevel::Level3, ONNX Runtime's own
default, so the native backend on aarch64 Windows is unaffected. On the tract path it
is a large change, because tract runs into_optimized() only when a session asks for
some level of optimization:

// ort-tract 0.2.0, api.rs:168
options.perform_optimizations = graph_optimization_level != GraphOptimizationLevel::ORT_DISABLE_ALL;

// ort-tract 0.2.0, session.rs:63
let graph = Arc::new(if options.perform_optimizations { model.into_optimized()? } else { model.into_typed()? });

This subsumes #1368, which sets the same level as a constant; whichever lands second
needs a trivial rebase.

Breaking changes

None. new and load_model keep their signatures and delegate to the new methods
with SessionOptions::default(). Wake word scores are unchanged; the default
optimization level is a speedup, not a behaviour change (asserted below).

MSRV

Unchanged.

Testing

cargo test -p livekit-wakeword --release — 5 integration tests plus the
SessionOptions doctest, all passing. Two tests are new:

• test_session_options_preserve_scores — the conservative-CPU options above,
  including a config entry, produce a byte-identical score to the default model.
  This is the regression test for the best-effort path: on any tract target it fails
  to construct at all if an unimplemented option is treated as an error.
• test_optimization_levels_and_per_model_options — Disable, Level1 and Level3
  each build a model that still scores positive.wav above threshold, and a
  per-classifier override loads alongside a default-options classifier with equal
  scores.

Neither test asserts on timing, so I measured separately that the level really does
reach the backend — 7 runs of predict() over a 2 s window, same process, release
build, Apple M-series:

optimization level	median predict
Disable (what main does today)	329 ms
Level3 (the new default)	53 ms

6.2x, consistent with the numbers in #1368. Laptop timings, so treat the magnitude as
the claim rather than the figures.

Async

No change. The diff introduces no .await and no runtime dependency.

[github-actions]

Changeset ✓

This PR includes a changeset covering all affected packages:

Package	Bump
livekit-wakeword	minor

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.