FunctionInvocationContext.cs

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System;
using System.Collections.Generic;
using Microsoft.Shared.Collections;
using Microsoft.Shared.Diagnostics;

namespace Microsoft.Extensions.AI;

/// <summary>Provides context for an in-flight function invocation.</summary>
public class FunctionInvocationContext
{
    /// <summary>
    /// A nop function used to allow <see cref="Function"/> to be non-nullable. Default instances of
    /// <see cref="FunctionInvocationContext"/> start with this as the target function.
    /// </summary>
    private static readonly AIFunction _nopFunction = AIFunctionFactory.Create(() => { }, nameof(FunctionInvocationContext));

    /// <summary>The chat contents associated with the operation that initiated this function call request.</summary>
    private IList<ChatMessage> _messages = Array.Empty<ChatMessage>();

    /// <summary>The AI function to be invoked.</summary>
    private AIFunction _function = _nopFunction;

    /// <summary>The function call content information associated with this invocation.</summary>
    private FunctionCallContent? _callContent;

    /// <summary>The arguments used with the function.</summary>
    private AIFunctionArguments? _arguments;

    /// <summary>Initializes a new instance of the <see cref="FunctionInvocationContext"/> class.</summary>
    public FunctionInvocationContext()
    {
    }

    /// <summary>Gets or sets the AI function to be invoked.</summary>
    public AIFunction Function
    {
        get => _function;
        set => _function = Throw.IfNull(value);
    }

    /// <summary>Gets or sets the arguments associated with this invocation.</summary>
    public AIFunctionArguments Arguments
    {
        get => _arguments ??= [];
        set => _arguments = Throw.IfNull(value);
    }

    /// <summary>Gets or sets the function call content information associated with this invocation.</summary>
    public FunctionCallContent CallContent
    {
        get => _callContent ??= new(string.Empty, _nopFunction.Name, EmptyReadOnlyDictionary<string, object?>.Instance);
        set => _callContent = Throw.IfNull(value);
    }

    /// <summary>Gets or sets the chat contents associated with the operation that initiated this function call request.</summary>
    public IList<ChatMessage> Messages
    {
        get => _messages;
        set => _messages = Throw.IfNull(value);
    }

    /// <summary>Gets or sets the chat options associated with the operation that initiated this function call request.</summary>
    public ChatOptions? Options { get; set; }

    /// <summary>Gets or sets the number of this iteration with the underlying client.</summary>
    /// <remarks>
    /// The initial request to the client that passes along the chat contents provided to the <see cref="FunctionInvokingChatClient"/>
    /// is iteration 1. If the client responds with a function call request, the next request to the client is iteration 2, and so on.
    /// </remarks>
    public int Iteration { get; set; }

    /// <summary>Gets or sets the index of the function call within the iteration.</summary>
    /// <remarks>
    /// The response from the underlying client may include multiple function call requests.
    /// This index indicates the position of the function call within the iteration.
    /// </remarks>
    public int FunctionCallIndex { get; set; }

    /// <summary>Gets or sets the total number of function call requests within the iteration.</summary>
    /// <remarks>
    /// The response from the underlying client might include multiple function call requests.
    /// This count indicates how many there were.
    /// </remarks>
    public int FunctionCount { get; set; }

    /// <summary>Gets or sets a value indicating whether to terminate the request.</summary>
    /// <remarks>
    /// In response to a function call request, the function might be invoked, its result added to the chat contents,
    /// and a new request issued to the wrapped client. If this property is set to <see langword="true"/>, that subsequent request
    /// will not be issued and instead the loop immediately terminated rather than continuing until there are no
    /// more function call requests in responses.
    /// <para>
    /// If multiple function call requests are issued as part of a single iteration (a single response from the inner <see cref="IChatClient"/>),
    /// setting <see cref="Terminate" /> to <see langword="true" /> may also prevent subsequent requests within that same iteration from being processed.
    /// </para>
    /// </remarks>
    public bool Terminate { get; set; }

    /// <summary>
    /// Gets or sets a value indicating whether the function invocation is occurring as part of a
    /// <see cref="IChatClient.GetStreamingResponseAsync"/> call as opposed to a <see cref="IChatClient.GetResponseAsync"/> call.
    /// </summary>
    public bool IsStreaming { get; set; }
}