AI-Studio/app/MindWork AI Studio/Tools/ToolCallingSystem/Harness/ToolCallingLoopContext.cs

using AIStudio.Chat;
using AIStudio.Provider;

namespace AIStudio.Tools.ToolCallingSystem.Harness;

/// <summary>
/// Everything one run of the tool calling loop needs besides its provider adapter.
/// </summary>
public sealed class ToolCallingLoopContext
{
    /// <summary>
    /// The chat the loop runs for. Tool results may raise its required provider confidence.
    /// </summary>
    public required ChatThread ChatThread { get; init; }

    /// <summary>
    /// The tools the model may call in this run.
    /// </summary>
    public required IReadOnlyList<(ToolDefinition Definition, IToolImplementation Implementation)> RunnableTools { get; init; }

    public required ToolExecutor ToolExecutor { get; init; }

    /// <summary>
    /// The provider running the conversation, needed to judge what a tool may return to it.
    /// </summary>
    public required IProvider Provider { get; init; }

    /// <summary>
    /// The assistant message being built, or null when there is none to update.
    /// </summary>
    /// <remarks>
    /// The loop writes the tool traces and the live status into this instance, which is already
    /// part of the chat thread. That is how the UI learns about a running tool without the loop
    /// having to yield anything.
    /// </remarks>
    public ContentText? CurrentAssistantContent { get; init; }

    public required string ProviderInstanceName { get; init; }

    public required LLMProviders ProviderType { get; init; }

    public required string ModelId { get; init; }

    /// <summary>
    /// Records one tool invocation for the UI.
    /// </summary>
    /// <remarks>
    /// Tells the UI right away, so a finished call shows up while the next one is still running.
    /// Waiting for the round to end would leave the user watching a list that lags behind what the
    /// model is doing.
    /// </remarks>
    public async Task AddToolInvocationAsync(ToolInvocationTrace trace)
    {
        if (this.CurrentAssistantContent is null)
            return;

        this.CurrentAssistantContent.ToolInvocations.Add(trace);
        await this.CurrentAssistantContent.StreamingEvent();
    }

    /// <summary>
    /// Hands the conversation the adapter has accumulated to the assistant message.
    /// </summary>
    /// <remarks>
    /// Called after every recording, not once per round: a round which reads five web pages is the
    /// one during which the request grows the most, and a number which only moves between rounds
    /// would stand still through exactly that.
    /// </remarks>
    /// <param name="adapter">The adapter of this run, which knows what it has recorded.</param>
    public async Task PublishPendingToolConversationAsync(IToolCallingProviderAdapter adapter)
    {
        if (this.CurrentAssistantContent is null)
            return;

        this.CurrentAssistantContent.PendingToolConversation = [..adapter.RecordedRequestTexts];
        await this.CurrentAssistantContent.StreamingEvent();
    }

    /// <summary>
    /// Tells the UI that the named tools are running.
    /// </summary>
    public async Task ShowToolRuntimeStatusAsync(IEnumerable<string> toolNames)
    {
        if (this.CurrentAssistantContent is null)
            return;

        this.CurrentAssistantContent.ToolRuntimeStatus = new ToolRuntimeStatus
        {
            IsRunning = true,
            ToolNames = [.. toolNames],
        };

        await this.CurrentAssistantContent.StreamingEvent();
    }

    /// <summary>
    /// Clears the running-tool status.
    /// </summary>
    /// <remarks>
    /// Must happen on every path leaving a round, including the failing ones: a status left
    /// behind tells the user a tool is still running when nothing is.
    /// </remarks>
    public async Task ResetToolRuntimeStatusAsync()
    {
        if (this.CurrentAssistantContent is null)
            return;

        this.CurrentAssistantContent.ToolRuntimeStatus = new();
        await this.CurrentAssistantContent.StreamingEvent();
    }
}