Module inference_path_selector 

Device-optimal inference path selection.

Design intent (Timothy): a benchmark utility identifies the fastest method on this machine (wgpu DX12 / Vulkan / Metal / GL, optional CUDA lane, CPU) and the product picks that path — not a static hierarchy.

What is selected

Axis	Candidates	Measured by
API backend	dx12, vulkan, metal, gl	Hardware passport GEMV + decode-proxy
Compute lane	portable (resident wgpu), cuda (forge TC + Q4 SoA GEMV)	Capability flags + optional micro-policy
Quant profile	INT4 SoA weights, INT8 KV, quant-graph quality	A2000-class bandwidth + rights mode
Prefill vs decode	TC GEMM when batch/dims allow; GEMV for m=1 decode	Shape policy, not GEMV score alone

Vulkan and DX12 both use the same resident weight plan (VRAM-sticky multi-weight); there is no separate “Vulkan multi-weight” — multi-weight without host RT is the resident decode path. CUDA multi-weight is the optional densify/Q4 device slab.

Env pins always win: QUALIA_WGPU_BACKEND, QUALIA_INFERENCE_MODE, QUALIA_PATH_AUTO=0.

Structs

InferencePathPlan

Full selected plan for this process / host.

Enums

ComputeLane

How decode math is executed after the wgpu API backend is chosen.

QuantProfile

Quantization / quality profile for consumer GPUs.

Functions

apply_inference_path_plan

Apply plan to process toggles (once per process unless force).

bootstrap_optimal_inference_path

Resolve + apply if QUALIA_PATH_AUTO enabled. Called from bootstrap_inference_mode.

format_path_plan

Operator-facing summary (CLI / doctor).

last_inference_path_plan

Last plan applied (or resolved without apply).

path_auto_enabled

Whether auto path selection is enabled (QUALIA_PATH_AUTO default on).

resolve_inference_path_plan

Resolve the optimal plan from passport + host capabilities (does not mutate process yet).

run_path_select_cli

Probe passport (optional re-probe) and print/apply plan. Used by CLI.