// Copyright (c) Microsoft. All rights reserved.

using Microsoft.Extensions.AI;
using Microsoft.Extensions.AI.Agents;
using Microsoft.Shared.Diagnostics;
using OpenAI.Chat;

namespace OpenAI;

/// <summary>
/// Provides extension methods for <see cref="AgentRunResponse"/> to extract native OpenAI response objects
/// from the Microsoft Extensions AI Agent framework responses.
/// </summary>
/// <remarks>
/// These extensions enable developers to access the underlying OpenAI SDK objects when working with
/// AI agents that are backed by OpenAI services. The methods extract strongly-typed OpenAI responses
/// from the <see cref="AgentRunResponse.RawRepresentation"/> property, providing a bridge between
/// the Microsoft Extensions AI framework and the native OpenAI SDK types.
/// </remarks>
public static class AgentRunResponseExtensions
{
    /// <summary>
    /// Extracts a native OpenAI <see cref="ChatCompletion"/> object from an <see cref="AgentRunResponse"/>.
    /// </summary>
    /// <param name="agentResponse">The agent response containing the raw OpenAI representation.</param>
    /// <returns>The native OpenAI <see cref="ChatCompletion"/> object.</returns>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="agentResponse"/> is <see langword="null"/>.</exception>
    /// <exception cref="ArgumentException">
    /// Thrown when the <see cref="AgentRunResponse.RawRepresentation"/> is not a <see cref="ChatCompletion"/> object.
    /// This typically occurs when the agent response was not generated by an OpenAI chat completion service
    /// or when the underlying representation has been modified or corrupted.
    /// </exception>
    /// <remarks>
    /// <para>
    /// This method provides access to the native OpenAI <see cref="ChatCompletion"/> object that was used
    /// to generate the agent response. This is useful when you need to access OpenAI-specific properties
    /// or metadata that are not exposed through the Microsoft Extensions AI abstractions.
    /// </para>
    /// </remarks>
    public static ChatCompletion AsChatCompletion(this AgentRunResponse agentResponse)
    {
        Throw.IfNull(agentResponse);

        if (agentResponse.RawRepresentation is ChatResponse chatResponse)
        {
            return chatResponse.RawRepresentation is ChatCompletion chatCompletion
                ? chatCompletion
                : throw new ArgumentException("ChatResponse.RawRepresentation must be a ChatCompletion");
        }
        throw new ArgumentException("AgentRunResponse.RawRepresentation must be a ChatResponse");
    }
}