UAIX.LmRuntime / Package guide

UAIX.LmRuntime.Acceleration

Explicit backend contracts, registration, capability declarations, local probing, deterministic selection, and visible CPU fallback.

Required For explicit backend registration, probing, selection, and fallback evidence

UAIX.LmRuntime.Acceleration

Explicit backend contracts, registration, capability declarations, local probing, deterministic selection, and visible CPU fallback.

Overview

Acceleration owns the runtime-neutral control plane for local execution backends. Hosts register backend instances, probe them in stable order, choose with a declared policy, and receive the selected backend, device, capabilities, diagnostics, and CPU-fallback state. Installing a backend package does not register it or grant execution authority.

Who should use it Host authors, runtime integrators, diagnostics tooling, and applications that must distinguish declared compatibility from proven local availability.

Install

.NET CLI
dotnet add package UAIX.LmRuntime.Acceleration
Project file
<PackageReference Include="UAIX.LmRuntime.Acceleration" />

Version policy: The documentation deliberately omits UAIX.LmRuntime package version numbers. Resolve and pin versions through your normal dependency-management and lock-file process.

Review the current package metadata, frameworks, dependencies, and downloads on NuGet ↗

Direct package dependencies

None within the UAIX.LmRuntime package family.

Package role and boundaries

Required For explicit backend registration, probing, selection, and fallback evidence

  • You need an explicit registry of local execution backends.
  • You need CPU/GPU selection policies with visible fallback state.
  • You need capability, device, runtime-identifier, native-asset, and probe diagnostics.
  • You are implementing a host-owned backend adapter against IRuntimeBackend.

Boundary

  • It does not execute a GGUF model or perform tensor math.
  • It does not load drivers, download assets, invoke provider APIs, start subprocesses, or perform remote inference.
  • A capability declaration is not proof that a backend is available on the current machine.

Registration is explicit

The host controls which backend instances enter the registry. A package reference alone does not make a backend selectable.

Selection is evidence-bearing

The result identifies the backend, device, capabilities, diagnostics, and whether a GPU-prefer policy used CPU fallback.

Require policies fail closed

RequireGpu and RequireBackendId return a failed selection when the named execution class cannot prove availability.

Key types

These are the main entry points for this package. The generated reference below includes every documented type and member represented by public package XML documentation.

Coding examples

Examples use public package signatures documented on LMRuntime.com. Model paths, hashes, byte counts, prompts, and host-specific identifiers remain application inputs.

Register and select the managed CPU backend

Compose Acceleration with Backends.CpuManaged and require a CPU-capable local backend.

RequireCpuExample.cs
using UAIX.LmRuntime.Acceleration;
using UAIX.LmRuntime.Backends.CpuManaged;

var registry = new RuntimeBackendRegistry();
registry.AddUaixCpuManagedBackend();

var selector = new RuntimeBackendSelector(registry);
RuntimeSelectionResult result = await selector.SelectAsync(
    new RuntimeBackendOptions
    {
        Policy = RuntimeSelectionPolicy.RequireCpu
    });

if (!result.Succeeded)
{
    throw new InvalidOperationException(result.FailureReason);
}

Console.WriteLine(result.SelectedBackendId);
Console.WriteLine(result.SelectedDevice?.DeviceId);

Boundary: This composition requires the Backends.CpuManaged package. Selection does not load a model; it establishes explicit backend identity.

Prefer CUDA and expose managed CPU fallback

Register a diagnostic CUDA path and a working managed CPU path, then observe the fallback bit.

PreferGpuFallbackExample.cs
using UAIX.LmRuntime.Acceleration;
using UAIX.LmRuntime.Backends.CpuManaged;
using UAIX.LmRuntime.Backends.Cuda;

var registry = new RuntimeBackendRegistry();
registry.AddUaixCudaBackend();
registry.AddUaixCpuManagedBackend();

var selector = new RuntimeBackendSelector(registry);
RuntimeSelectionResult result = await selector.SelectAsync(
    new RuntimeBackendOptions
    {
        Policy = RuntimeSelectionPolicy.PreferGpu,
        AllowCpuFallback = true
    });

Console.WriteLine($"Succeeded: {result.Succeeded}");
Console.WriteLine($"Backend: {result.SelectedBackendId}");
Console.WriteLine($"CPU fallback: {result.UsedCpuFallback}");
foreach (string diagnostic in result.Diagnostics)
{
    Console.WriteLine(diagnostic);
}

Boundary: The supplied CUDA registration is diagnostic and probes unavailable until a native adapter proves assets, runtime libraries, and a device.

Require GPU and fail without proven availability

Use a require policy when CPU substitution would violate the host workload contract.

RequireGpuExample.cs
using UAIX.LmRuntime.Acceleration;
using UAIX.LmRuntime.Backends.Cuda;

var registry = new RuntimeBackendRegistry();
registry.AddUaixCudaBackend();

var selector = new RuntimeBackendSelector(registry);
RuntimeSelectionResult result = await selector.SelectAsync(
    new RuntimeBackendOptions
    {
        Policy = RuntimeSelectionPolicy.RequireGpu,
        AllowCpuFallback = false,
        RequireNativeAssets = true
    });

if (!result.Succeeded)
{
    Console.Error.WriteLine(result.FailureReason);
    foreach (string diagnostic in result.Diagnostics)
    {
        Console.Error.WriteLine(diagnostic);
    }
}

Boundary: RequireGpu never reports a managed CPU selection as GPU execution.

Probe every registered backend directly

Build a diagnostics view without asking the selector to choose an execution path.

ProbeRegistryExample.cs
using UAIX.LmRuntime.Acceleration;
using UAIX.LmRuntime.Backends.CpuManaged;
using UAIX.LmRuntime.Backends.DirectML;
using UAIX.LmRuntime.Backends.Vulkan;

var registry = new RuntimeBackendRegistry();
registry
    .AddUaixCpuManagedBackend()
    .AddUaixDirectMlBackend()
    .AddUaixVulkanBackend();

var probeSettings = new RuntimeBackendOptions
{
    RequestedRuntimeIdentifier = System.Runtime.InteropServices.RuntimeInformation.RuntimeIdentifier
};

foreach (IRuntimeBackend backend in registry.GetBackends())
{
    RuntimeBackendProbeResult probe = await backend.ProbeAsync(probeSettings);
    Console.WriteLine($"{backend.Id}: available={probe.IsAvailable}");
    foreach (string diagnostic in probe.Diagnostics)
    {
        Console.WriteLine($"  {diagnostic}");
    }
}

Boundary: Probing is local and diagnostic. The registry order is preserved so reports and selection remain deterministic.

Select one required backend identifier

Pin selection to the stable backend ID rather than relying on registration order.

RequireBackendIdExample.cs
using UAIX.LmRuntime.Acceleration;
using UAIX.LmRuntime.Backends.CpuManaged;

var registry = new RuntimeBackendRegistry();
registry.AddUaixCpuManagedBackend();

var selector = new RuntimeBackendSelector(registry);
RuntimeSelectionResult result = await selector.SelectAsync(
    new RuntimeBackendOptions
    {
        Policy = RuntimeSelectionPolicy.RequireBackendId,
        PreferredBackendId = CpuManagedRuntimeBackend.BackendId
    });

Console.WriteLine(result.Succeeded
    ? $"Selected {result.SelectedBackendId}"
    : result.FailureReason);

Boundary: RequireBackendId returns failure when the ID is empty, unregistered, or unavailable.

Inspect declared capabilities without treating them as availability

Read backend capability metadata and then check the independent probe result.

CapabilityAndProbeExample.cs
using UAIX.LmRuntime.Acceleration;
using UAIX.LmRuntime.Backends.Cuda;

IRuntimeBackend backend = new CudaRuntimeBackend();
RuntimeBackendCapabilities declared = backend.Capabilities;
RuntimeBackendProbeResult probe = await backend.ProbeAsync(new RuntimeBackendOptions());

Console.WriteLine($"API: {declared.BackendApiName}");
Console.WriteLine($"Declares GPU execution: {declared.SupportsGpuExecution}");
Console.WriteLine($"Native asset state: {declared.NativeAssetState}");
Console.WriteLine($"Available now: {probe.IsAvailable}");

Boundary: Capabilities describe the backend family. Probe evidence decides whether execution is available in the current host.

Generated API reference

Expand a type to review its documented fields, properties, constructors, methods, parameter descriptions, and return descriptions. Browser Find also works across the closed detail elements.

DiagnosticRuntimeBackendUAIX.LmRuntime.Acceleration 5 members

Provides shared diagnostic behavior for backend packages that declare compatibility before native execution is proven.

The class keeps package-visible backend declarations DRY. It performs no native loads, subprocess execution, provider calls, network access, or model downloads; concrete packages remain responsible only for naming their compatibility API, runtime identifiers, and package-specific diagnostics.

Property Capabilities

Gets the backend capability declaration.

Property DisplayName

Gets the human-readable backend name.

Property Id

Gets the stable backend identifier.

Property Kind

Gets the backend kind.

Method ProbeAsync(UAIX.LmRuntime.Acceleration.RuntimeBackendOptions,System.Threading.CancellationToken)

Probes a diagnostic backend and reports unavailable until native assets, runtime libraries, and devices are proven.

options
The caller-supplied probing and selection options.
cancellationToken
A token that cancels the probe.

Returns: The backend probe result.

IRuntimeBackendUAIX.LmRuntime.Acceleration 5 members

Defines a local runtime backend that can report capabilities and probe available devices.

Backends are package-visible compatibility surfaces. Implementations must not perform hidden downloads, provider calls, subprocess execution, or remote inference during probing or selection.

Property Capabilities

Gets the backend capability declaration.

Property DisplayName

Gets the human-readable backend name.

Property Id

Gets the stable backend identifier.

Property Kind

Gets the backend kind.

Method ProbeAsync(UAIX.LmRuntime.Acceleration.RuntimeBackendOptions,System.Threading.CancellationToken)

Probes the backend for local execution availability and devices.

options
The caller-supplied probing and selection options.
cancellationToken
A token that cancels the probe.

Returns: The backend probe result.

IRuntimeBackendRegistryUAIX.LmRuntime.Acceleration 3 members

Defines a registry of runtime backends available to a host application.

The registry is explicit and local. Merely installing a package does not grant hidden runtime authority unless the host registers the backend instance.

Method FindById(string)

Finds a backend by identifier.

backendId
The backend identifier to find.

Returns: The matching backend, or when no backend is registered for the ID.

Method GetBackends

Gets the currently registered runtime backends.

Returns: The ordered registered backend list.

Method Register(UAIX.LmRuntime.Acceleration.IRuntimeBackend)

Registers one runtime backend.

backend
The backend to register.
IRuntimeBackendSelectorUAIX.LmRuntime.Acceleration 1 member

Defines backend selection over a registered set of local runtime backends.

Selection returns explicit backend and device identity so CPU fallback is never confused with GPU execution.

Method SelectAsync(UAIX.LmRuntime.Acceleration.RuntimeBackendOptions,System.Threading.CancellationToken)

Selects a backend according to the supplied policy and options.

options
The backend selection options.
cancellationToken
A token that cancels selection.

Returns: The backend selection result.

RuntimeBackendCapabilitiesUAIX.LmRuntime.Acceleration 13 members

Reports the execution and compatibility capabilities declared by a runtime backend.

Capabilities are package-visible declarations. Availability is still decided by probing native assets, runtime libraries, drivers, and devices before a backend is selected for execution.

Property BackendApiName

Gets or sets the backend API name, such as CUDA, DirectML, Vulkan, ROCm, Metal, or managed CPU.

Property Diagnostics

Gets diagnostic messages describing compatibility, package state, and probe status.

Property NativeAssetState

Gets or sets the backend-reported native asset state.

Property RuntimeIdentifiers

Gets runtime identifiers supported or observed by the backend package.

Property SupportsCpuOnlyExecution

Gets or sets a value indicating whether the backend can execute without GPU hardware.

Property SupportsDeviceSelection

Gets or sets a value indicating whether callers can select among backend devices.

Property SupportsGguf

Gets or sets a value indicating whether the backend supports GGUF model inputs.

Property SupportsGpuExecution

Gets or sets a value indicating whether the backend can execute on a GPU device.

Property SupportsLlama

Gets or sets a value indicating whether the backend supports LLaMA-family model binding.

Property SupportsMemoryQuery

Gets or sets a value indicating whether the backend can query device or execution memory.

Property SupportsStreaming

Gets or sets a value indicating whether the backend supports streaming token output.

Property UsesGpuAcceleration

Gets or sets a value indicating whether the backend uses GPU acceleration when it executes successfully.

Property UsesNativeInference

Gets or sets a value indicating whether the backend uses native inference components.

RuntimeBackendKindUAIX.LmRuntime.Acceleration 8 members

Identifies the accelerator API family or execution class represented by a runtime backend.

The value describes the backend package family, not a claim that a device, driver, or native library is available on the current machine.

Field CpuManaged

The managed CPU reference backend.

Field Cuda

An NVIDIA CUDA backend.

Field DirectML

A Windows DirectML backend.

Field ExternalNative

A backend supplied by an external native package or host adapter.

Field Metal

An Apple Metal backend.

Field Rocm

An AMD ROCm backend.

Field Unknown

An unknown or not-yet-classified backend.

Field Vulkan

A Vulkan compute backend.

RuntimeBackendOptionsUAIX.LmRuntime.Acceleration 7 members

Provides caller-supplied backend selection and probing options.

These options never authorize hidden downloads, provider fallback, subprocess execution, or remote inference. They only describe how registered local backends should be probed and selected.

Property AllowCpuFallback

Gets or sets a value indicating whether prefer policies may fall back to CPU execution.

Property NativeAssetDirectory

Gets or sets an optional directory that a backend may inspect for native assets.

Property Policy

Gets or sets the backend selection policy.

Property PreferredBackendId

Gets or sets the preferred or required backend identifier for backend-id policies.

Property PreferredDeviceId

Gets or sets the preferred backend-local device identifier when device selection is supported.

Property RequestedRuntimeIdentifier

Gets or sets the runtime identifier requested by the caller, when different from the current process.

Property RequireNativeAssets

Gets or sets a value indicating whether a selected backend must have native assets available.

RuntimeBackendProbeResultUAIX.LmRuntime.Acceleration 6 members

Reports the result of probing one registered runtime backend.

A backend may declare capabilities but still probe unavailable when native assets, runtime libraries, drivers, or devices are absent.

Property BackendId

Gets or sets the backend identifier.

Property BackendKind

Gets or sets the backend kind.

Property Capabilities

Gets or sets the backend capabilities.

Property Devices

Gets discovered devices reported by the backend.

Property Diagnostics

Gets probe diagnostics.

Property IsAvailable

Gets or sets a value indicating whether the backend is available for execution.

RuntimeBackendRegistryUAIX.LmRuntime.Acceleration 3 members

Provides an in-memory explicit registry of local runtime backends.

Registration order is preserved so callers can make deterministic selection decisions.

Method FindById(string)

Finds a backend by identifier.

backendId
The backend identifier to find.

Returns: The matching backend, or when no backend is registered for the ID.

Method GetBackends

Gets the currently registered runtime backends.

Returns: The ordered registered backend list.

Method Register(UAIX.LmRuntime.Acceleration.IRuntimeBackend)

Registers one runtime backend.

backend
The backend to register.
RuntimeBackendSelectorUAIX.LmRuntime.Acceleration 2 members

Selects a local runtime backend from an explicit registry.

The selector probes registered backends and reports fallback identity instead of silently substituting one execution class for another.

Method RuntimeBackendSelector(UAIX.LmRuntime.Acceleration.IRuntimeBackendRegistry)

Initializes a new instance of the UAIX.LmRuntime.Acceleration.RuntimeBackendSelector class.

registry
The backend registry to select from.
Method SelectAsync(UAIX.LmRuntime.Acceleration.RuntimeBackendOptions,System.Threading.CancellationToken)

Selects a backend according to the supplied policy and options.

options
The backend selection options.
cancellationToken
A token that cancels selection.

Returns: The backend selection result.

RuntimeDeviceDescriptorUAIX.LmRuntime.Acceleration 12 members

Describes one CPU or accelerator device discovered by a runtime backend probe.

Device descriptors are diagnostic evidence. They should identify the device that would execute work without exposing private file paths, credentials, prompt text, or generated text.

Property BackendApiName

Gets or sets the acceleration API name associated with the device.

Property BackendId

Gets or sets the identifier of the backend that reported the device.

Property BackendKind

Gets or sets the backend kind that reported the device.

Property ComputeCapability

Gets or sets the backend-reported compute capability, feature level, or API version.

Property DeviceId

Gets or sets the stable backend-local device identifier.

Property Diagnostics

Gets diagnostic messages associated with the device descriptor.

Property DisplayName

Gets or sets the human-readable device name.

Property IsCpu

Gets or sets a value indicating whether the descriptor represents CPU execution.

Property IsGpu

Gets or sets a value indicating whether the descriptor represents GPU execution.

Property MemoryBytes

Gets or sets the backend-reported device memory in bytes when known.

Property RuntimeIdentifier

Gets or sets the runtime identifier associated with the probed process.

Property Vendor

Gets or sets the vendor or implementation owner reported by the backend.

RuntimeSelectionPolicyUAIX.LmRuntime.Acceleration 6 members

Defines how the selector chooses among registered runtime backends.

Policies that prefer a backend may fall back when the options allow it. Policies that require a backend fail clearly when the required capability is unavailable.

Field PreferBackendId

Prefer a specific backend identifier and fall back only when fallback is permitted.

Field PreferCpu

Prefer a CPU-capable backend but allow a different available backend when CPU is absent.

Field PreferGpu

Prefer an available GPU backend and fall back to CPU only when fallback is permitted.

Field RequireBackendId

Select only a specific backend identifier.

Field RequireCpu

Select only a CPU-capable backend.

Field RequireGpu

Select only an available GPU backend.

RuntimeSelectionResultUAIX.LmRuntime.Acceleration 9 members

Reports the selected backend, selected device, and any fallback used by a selection policy.

Selection results make CPU fallback explicit so callers never mistake fallback execution for GPU execution.

Property Diagnostics

Gets selection diagnostics.

Property FailureReason

Gets or sets the selection failure reason when selection did not succeed.

Property Policy

Gets or sets the policy used for selection.

Property SelectedBackendId

Gets or sets the selected backend identifier.

Property SelectedBackendKind

Gets or sets the selected backend kind.

Property SelectedCapabilities

Gets or sets the selected backend capabilities.

Property SelectedDevice

Gets or sets the selected device descriptor.

Property Succeeded

Gets or sets a value indicating whether selection succeeded.

Property UsedCpuFallback

Gets or sets a value indicating whether a GPU-prefer policy fell back to CPU execution.

Frequently asked questions

Does installing a backend register it?

No. The host must construct or add the backend to an IRuntimeBackendRegistry.

Can PreferGpu silently run on CPU?

No. CPU fallback requires AllowCpuFallback and is reported through UsedCpuFallback and diagnostics.

Does Acceleration execute inference?

No. It owns contracts, registration, probing, selection, and evidence. Model execution remains in the execution packages.

What should a custom backend prove?

Its probe should distinguish native assets, runtime libraries, drivers, devices, policy restrictions, and selected device identity without exposing private prompt or path content.