TieredProviderSelectorOptions

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Providers

TieredProviderSelectorOptions Class

Configuration for TieredProviderSelector<TQuery,TResult> controlling how exceptions thrown by providers are handled.

public sealed record TieredProviderSelectorOptions : System.IEquatable<NexusLabs.Needlr.AgentFramework.Providers.TieredProviderSelectorOptions>

Inheritance System.Object 🡒 TieredProviderSelectorOptions

Implements System.IEquatable<TieredProviderSelectorOptions>

Remarks

The selector evaluates FailurePolicies in order against each thrown exception (first match wins). When a policy matches, the selector falls through to the next provider, optionally caches a per-provider skip-until timestamp so future calls bypass the failing provider for a configurable duration, and optionally invokes the policy's OnHit callback. When no policy matches, the exception is re-thrown unchanged.

Use Default to preserve the framework's historical behaviour (ProviderUnavailableException falls through, no skip, no callback) and extend it with with-clones to add custom policies:

var options = TieredProviderSelectorOptions.Default with
{
    FailurePolicies =
    [
        .. TieredProviderSelectorOptions.Default.FailurePolicies,
        new ProviderFailurePolicy(
            Match: ex => ex is ApiAuthException,
            SkipDuration: TimeSpan.FromMinutes(5)),
    ],
};

Properties

TieredProviderSelectorOptions.Default Property

Default options preserving the framework's historical fall-through behaviour: ProviderUnavailableException matches with no skip and no callback, so the selector falls through to the next provider on every PUE without any cross-call memory of the failure. Other exception types propagate raw.

public static NexusLabs.Needlr.AgentFramework.Providers.TieredProviderSelectorOptions Default { get; }

Property Value

TieredProviderSelectorOptions

Remarks

Use this as the starting point for custom configurations: TieredProviderSelectorOptions.Default with { FailurePolicies = [...] }.

TieredProviderSelectorOptions.FailurePolicies Property

Ordered list of failure policies. The first policy whose Match predicate returns true for a thrown exception is applied; subsequent policies are not evaluated. Defaults to an empty list (every exception propagates raw).

public System.Collections.Generic.IReadOnlyList<NexusLabs.Needlr.AgentFramework.Providers.ProviderFailurePolicy> FailurePolicies { get; init; }

Property Value

System.Collections.Generic.IReadOnlyList<ProviderFailurePolicy>