| | | 1 | | namespace InferenceEngine.Core.Diagnostics; |
| | | 2 | | |
| | | 3 | | /// <summary>Lifecycle position of an inference engine.</summary> |
| | | 4 | | public enum EngineLoadState |
| | | 5 | | { |
| | | 6 | | /// <summary>Never loaded, disposed, or no load attempt yet.</summary> |
| | | 7 | | NotLoaded = 0, |
| | | 8 | | |
| | | 9 | | /// <summary><c>LoadAsync</c> is in flight (model resolution, provider selection, session |
| | | 10 | | /// construction). For out-of-process engines this spans worker spawn + IPC handshake.</summary> |
| | | 11 | | Loading, |
| | | 12 | | |
| | | 13 | | /// <summary>Session ready (possibly via CPU fallback — inspect |
| | | 14 | | /// <see cref="InferenceEngineStatus.Info"/> for provider/fallback).</summary> |
| | | 15 | | Loaded, |
| | | 16 | | |
| | | 17 | | /// <summary><c>LoadAsync</c> threw. <see cref="InferenceEngineStatus.Info"/> carries the |
| | | 18 | | /// partial provider-selection trail when available; <see cref="InferenceEngineStatus.LoadError"/> |
| | | 19 | | /// carries the error.</summary> |
| | | 20 | | Failed, |
| | | 21 | | } |
| | | 22 | | |
| | | 23 | | /// <summary> |
| | | 24 | | /// The consumer-facing object model for one engine's state: a single immutable snapshot covering |
| | | 25 | | /// lifecycle (<see cref="State"/>), runtime details (<see cref="Info"/>) and failure details |
| | | 26 | | /// (<see cref="LoadError"/>). Delivered both as a pollable property |
| | | 27 | | /// (<c>BaseInferenceEngine{TInput,TOutput}.Status</c>, mirrored onto out-of-process proxies) and |
| | | 28 | | /// via the <c>InferenceEngineOptions.OnStatusChanged</c> callback on every transition. |
| | | 29 | | /// </summary> |
| | | 30 | | /// <remarks> |
| | | 31 | | /// The graph consumers program against: |
| | | 32 | | /// <code> |
| | | 33 | | /// InferenceEngineOptions // configuration (model, GPU flags, callbacks) |
| | | 34 | | /// └─ OnStatusChanged(InferenceEngineStatus) |
| | | 35 | | /// ├─ State: EngineLoadState // NotLoaded → Loading → Loaded | Failed |
| | | 36 | | /// ├─ Detail: string? // display-only phase text while Loading |
| | | 37 | | /// ├─ Info: InferenceEngineInfo // Provider, DeviceId, ModelName/Path/Source, |
| | | 38 | | /// │ IsFallback + FallbackReason, Checks trail |
| | | 39 | | /// │ (partial — checks only — when State=Failed) |
| | | 40 | | /// └─ LoadError: string? // populated when State=Failed |
| | | 41 | | /// </code> |
| | | 42 | | /// <see cref="InferenceEngineOptions.OnSessionInitialized"/> remains as the success-only hook; |
| | | 43 | | /// new consumers should prefer <c>OnStatusChanged</c>, which also covers failures. |
| | | 44 | | /// </remarks> |
| | | 45 | | public sealed record InferenceEngineStatus |
| | | 46 | | { |
| | 366 | 47 | | public EngineLoadState State { get; init; } = EngineLoadState.NotLoaded; |
| | | 48 | | |
| | | 49 | | /// <summary>Runtime details. Full when <see cref="EngineLoadState.Loaded"/>; partial |
| | | 50 | | /// (provider-selection checks, <c>Provider=Unknown</c>) when <see cref="EngineLoadState.Failed"/>; |
| | | 51 | | /// null while NotLoaded/Loading.</summary> |
| | 88 | 52 | | public InferenceEngineInfo? Info { get; init; } |
| | | 53 | | |
| | | 54 | | /// <summary>The error that failed the load (exception message, or the worker-reported error |
| | | 55 | | /// for out-of-process engines). Null unless <see cref="State"/> is Failed.</summary> |
| | 28 | 56 | | public string? LoadError { get; init; } |
| | | 57 | | |
| | | 58 | | /// <summary>Best-effort human-readable phase text while <see cref="State"/> is |
| | | 59 | | /// <see cref="EngineLoadState.Loading"/> (e.g. "Starting engine worker…", |
| | | 60 | | /// "Constructing inference session…", "Compiling MIGraphX kernels…"). Consumed for progress |
| | | 61 | | /// UI during slow first loads; null means "no finer phase is known". Not a stable contract — |
| | | 62 | | /// treat as display text only.</summary> |
| | 234 | 63 | | public string? Detail { get; init; } |
| | | 64 | | |
| | | 65 | | /// <summary>When this snapshot was produced (UTC).</summary> |
| | 308 | 66 | | public DateTimeOffset Timestamp { get; init; } = DateTimeOffset.UtcNow; |
| | | 67 | | |
| | | 68 | | /// <summary>True when the engine is loaded AND running on a hardware provider |
| | | 69 | | /// (not CPU, not unknown).</summary> |
| | | 70 | | public bool IsGpuActive => |
| | 3 | 71 | | State == EngineLoadState.Loaded |
| | 3 | 72 | | && Info is not null |
| | 3 | 73 | | && Info.Provider is not (InferenceProvider.Cpu or InferenceProvider.Unknown); |
| | | 74 | | |
| | 342 | 75 | | public static InferenceEngineStatus NotLoaded { get; } = new(); |
| | | 76 | | } |