Model Adapters for Machine Intelligence Runtime

using System.ComponentModel.DataAnnotations;

/// <summary>Describes model capabilities used for route selection.</summary>
public sealed record ModelCapabilityProfile
{
    /// <summary>Gets the stable model route key.</summary>
    [Display(Name = "Route Key")]
    public required string RouteKey { get; init; }

    /// <summary>Gets the maximum supported input units.</summary>
    [Display(Name = "Context Limit")]
    public required int ContextLimit { get; init; }

    /// <summary>Gets whether structured output is supported.</summary>
    [Display(Name = "Supports Structured Output")]
    public required bool SupportsStructuredOutput { get; init; }
}

/// <summary>Contains a normalized model request.</summary>
public sealed record ModelRequest
{
    /// <summary>Gets the prompt-contract version.</summary>
    [Display(Name = "Prompt Contract Version")]
    public required string PromptContractVersion { get; init; }

    /// <summary>Gets the sealed context items.</summary>
    [Display(Name = "Context Items")]
    public required IReadOnlyList<string> ContextItems { get; init; }
}

/// <summary>Contains a normalized candidate and usage details.</summary>
public sealed record ModelCandidate
{
    /// <summary>Gets the candidate content.</summary>
    [Display(Name = "Content")]
    public required string Content { get; init; }

    /// <summary>Gets model usage metadata.</summary>
    [Display(Name = "Usage")]
    public required ModelUsage Usage { get; init; }
}

/// <summary>Contains normalized model usage.</summary>
public sealed record ModelUsage
{
    /// <summary>Gets the input units charged by the adapter.</summary>
    [Display(Name = "Input Units")]
    public required long InputUnits { get; init; }

    /// <summary>Gets the output units charged by the adapter.</summary>
    [Display(Name = "Output Units")]
    public required long OutputUnits { get; init; }
}

/// <summary>Normalizes a model provider boundary.</summary>
public interface IModelAdapter
{
    /// <summary>Gets the route capability profile.</summary>
    /// <param name="cancellationToken">Signals cancellation of capability discovery.</param>
    /// <returns>The current capability profile.</returns>
    Task<ModelCapabilityProfile> GetCapabilitiesAsync(CancellationToken cancellationToken);

    /// <summary>Streams normalized model candidates.</summary>
    /// <param name="request">The normalized request.</param>
    /// <param name="cancellationToken">Stops the provider stream and releases resources.</param>
    /// <returns>An asynchronous candidate stream.</returns>
    IAsyncEnumerable<ModelCandidate> StreamAsync(
        ModelRequest request,
        CancellationToken cancellationToken);
}

/// <summary>Represents a normalized model-adapter failure.</summary>
public sealed class ModelAdapterException : Exception
{
    /// <summary>Initializes a normalized adapter failure.</summary>
    /// <param name="code">The stable runtime error code.</param>
    /// <param name="message">The diagnostic message safe for evidence.</param>
    public ModelAdapterException(string code, string message) : base(message) => Code = code;

    /// <summary>Gets the stable runtime error code.</summary>
    public string Code { get; }
}