Ofbirds.LlmChain 1.0.5

Ofbirds.LlmChain

Ofbirds.LlmChain is a small, provider-neutral LLM failover chain for .NET applications. It supports text and vision requests through direct OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages HTTP transports.

The package owns no credentials and has no dependency on Ofbirds.Observability. Hosts supply credentials per provider and may connect the package's ActivitySource, Meter, and ILogger to any telemetry stack—or leave them unobserved.

var chain = new LlmChain(httpClient, providers,
    new DelegateLlmCredentialProvider((provider, _) =>
        ValueTask.FromResult<LlmCredentials?>(new(Environment.GetEnvironmentVariable(provider.Id)!))));

var result = await chain.CompleteAsync(LlmRequest.Text("Summarize this."), cancellationToken: ct);

For conversations, preserve message order and roles while keeping the request model domain-neutral:

var request = LlmRequest.Conversation([
    new("system", [new LlmTextPart("Be concise.")]),
    new("user", [new LlmTextPart("Summarize this.")])],
    new LlmRequestOptions(MaxOutputTokens: 256, Temperature: 0.2,
        ResponseFormat: new LlmResponseFormat("json_object")));

The options are provider-neutral hints; adapters map them to the selected wire protocol. Anthropic requests always include a positive max_tokens value (default 1024). System-role messages are lifted to Anthropic's top-level system field and removed from its message array; system messages containing images are rejected as a safe configuration failure. Anthropic data-URI images must be base64 encoded and are decoded into the Messages API's source.data field.

Providers are tried in Order. A host acceptance callback runs inside the chain, so a rejected result continues to the next provider. Caller cancellation is never treated as provider failure; timeouts, transient transport errors, and rate limits can fall through with bounded retry/cooldown behavior. Error messages and diagnostics contain provider identifiers, failure kinds, and status codes only—not prompts, images, credentials, raw bodies, or unsafe inner exceptions.

This v1 intentionally uses HttpClient and System.Text.Json; no vendor SDK is required.

Optional provider transports

Vendor-specific transports can be supplied by a companion package without adding that vendor's SDK or credential types to this core package. Register an ILlmProviderInvoker explicitly and configure the provider as LlmProtocol.Extension with the matching TransportId:

var providers = new[]
{
    new LlmProviderConfiguration(
        "bedrock", LlmProtocol.Extension, LlmCapabilities.Text,
        new Uri("https://provider.invalid"), "model")
    { TransportId = "bedrock-anthropic" }
};

var chain = new LlmChain(httpClient, providers, credentials,
    new LlmChainOptions { ProviderInvokers = [new BedrockInvoker(/* companion-package options */)] });

The core chain remains responsible for provider ordering, capability filtering, per-provider timeouts, transient retries, rate-limit cooldowns, acceptance callbacks, and diagnostics. An extension invoker performs one attempt with the supplied cancellation token and owns its vendor-specific authentication and wire format. It should throw LlmProviderException with a safe message for a typed failure. Core-only consumers do not register an invoker and retain the existing direct OpenAI and Anthropic behavior.

Companion compatibility and endpoint ownership

Ofbirds.LlmChain follows Semantic Versioning. Patch and minor releases within the same major version preserve the public ILlmProviderInvoker contract; a companion transport should pin a compatible Ofbirds.LlmChain major range and coordinate a major-version release when that contract changes. The transport is a separate optional package, so applications that do not use it do not acquire its SDKs or credentials.

For an extension provider, Endpoint is configuration metadata retained for a consistent provider record and diagnostics. The registered invoker owns the actual endpoint, authentication, signing, and wire format. The core chain does not send an extension request through its HttpClient or interpret extension credentials. This keeps vendor-specific endpoint and credential ownership in the companion package while preserving the same failover, timeout, cooldown, acceptance, and safe diagnostic behavior for every transport.