Skip to content

A programming framework for agentic AI

8.5 KB
Raw Blame
// Copyright (c) Microsoft Corporation. All rights reserved.
// Termination.cs

namespace Microsoft.AutoGen.AgentChat.Abstractions;

public static class TerminationConditionExtensions
{
    /// <summary>
    /// Combine this termination condition with another using a logical OR.
    /// </summary>
    /// <param name="other">Another termination condition.</param>
    /// <returns>The combined termination condition, with appropriate short-circuiting.</returns>
    public static ITerminationCondition Or(this ITerminationCondition this_, ITerminationCondition other)
    {
        return new CombinerCondition(CombinerCondition.Or, this_, other);
    }

    /// <summary>
    /// Combine this termination condition with another using a logical AND.
    /// </summary>
    /// <param name="other">Another termination condition.</param>
    /// <returns>The combined termination condition, with appropriate short-circuiting.</returns>
    public static ITerminationCondition And(this ITerminationCondition this_, ITerminationCondition other)
    {
        return new CombinerCondition(CombinerCondition.And, this_, other);
    }
}

/// <summary>
/// A stateful condition that determines when a conversation should be terminated.
///
/// A termination condition takes a sequences of <see cref="AgentMessage"/> objects since the last time the
/// condition was checked, and returns a <see cref="StopMessage"/> if the conversation should be terminated,
/// or <c>null</c> otherwise.
///
/// Once a termination condition has been reached, it must be <see cref="Reset()"/> before it can be used again.
///
/// Termination conditions can be combined using the <see cref="TerminationConditionExtensions.Or"/> and
/// <see cref="TerminationConditionExtensions.And"/> methods.
/// </summary>
public interface ITerminationCondition
{
    /// <summary>
    /// Checks if the termination condition has been reached
    /// </summary>
    public bool IsTerminated { get; }

    /// <summary>
    /// Check if the conversation should be terminated based on the messages received
    /// since the last time the condition was called.
    /// Return a <see cref="StopMessage"/> if the conversation should be terminated, or <c>null</c> otherwise.
    /// </summary>
    /// <param name="messages">The messages received since the last time the condition was called.</param>
    /// <returns>A <see cref="StopMessage"/> if the conversation should be terminated, or <c>null</c>
    /// otherwise.</returns>
    /// <exception cref="TerminatedException">If the termination condition has already been reached.</exception>
    public ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages);

    /// <summary>
    /// Resets the termination condition.
    /// </summary>
    public void Reset();

    /// <summary>
    /// Combine two termination conditions with another using an associative, short-circuiting OR.
    /// </summary>
    /// <param name="left">
    /// The left-hand side termination condition. If this condition is already a disjunction, the RHS condition is added to the list of clauses.
    /// </param>
    /// <param name="right">
    /// The right-hand side termination condition. If the LHS condition is already a disjunction, this condition is added to the list of clauses.
    /// </param>
    /// <returns>
    /// The combined termination condition, with appropriate short-circuiting.
    /// </returns>
    public static ITerminationCondition operator |(ITerminationCondition left, ITerminationCondition right)
    {
        return left.Or(right);
    }

    /// <summary>
    /// Combine two termination conditions with another using an associative, short-circuiting AND.
    /// </summary>
    /// <param name="left">
    /// The left-hand side termination condition. If this condition is already a conjunction, the RHS condition is added to the list of clauses.
    /// </param>
    /// <param name="right">
    /// The right-hand side termination condition. If the LHS condition is already a conjunction, this condition is added to the list of clauses.
    /// </param>
    /// <returns>
    /// The combined termination condition, with appropriate short-circuiting.
    /// </returns>
    public static ITerminationCondition operator &(ITerminationCondition left, ITerminationCondition right)
    {
        return left.And(right);
    }
}

/// <summary>
/// Exception thrown when a termination condition has already been reached.
/// </summary>
public sealed class TerminatedException : Exception
{
    public TerminatedException() : base("The termination condition has already been reached.")
    {
    }
}

/// <summary>
/// A termination condition that combines multiple termination conditions using a logical AND or OR.
/// </summary>
internal sealed class CombinerCondition : ITerminationCondition
{
    public const bool Conjunction = true;
    public const bool Disjunction = false;

    public const bool And = Conjunction;
    public const bool Or = Disjunction;

    private List<StopMessage> stopMessages = new List<StopMessage>();
    private List<ITerminationCondition> clauses;
    private readonly bool conjunction;

    /// <summary>
    /// Create a new <see cref="CombinerCondition"/> with the given conjunction and clauses.
    /// </summary>
    /// <param name="conjunction">The conjunction to use when combining the clauses.</param>
    /// <param name="clauses">The termination conditions to combine.</param>
    public CombinerCondition(bool conjunction, params IEnumerable<ITerminationCondition> clauses)
    {
        // Flatten the list of clauses by unwrapping included CombinerConditions if their
        // conjunctions match (since combiners with associative conjunctions can be hoisted).
        IEnumerable<ITerminationCondition> flattened =
            clauses.SelectMany(c =>
                    (c is CombinerCondition combiner && combiner.conjunction == conjunction)
                    ? (IEnumerable<ITerminationCondition>)combiner.clauses
                    : new[] { c });

        this.conjunction = conjunction;

        this.clauses = flattened.ToList();
    }

    /// <inheritdoc cref="ITerminationCondition.IsTerminated" />
    public bool IsTerminated { get; private set; }

    /// <inheritdoc cref="ITerminationCondition.Reset" />
    public void Reset()
    {
        this.stopMessages.Clear();
        this.clauses.ForEach(c => c.Reset());

        this.IsTerminated = false;
    }

    /// <inheritdoc cref="ITerminationCondition.CheckAndUpdateAsync" />
    public async ValueTask<StopMessage?> CheckAndUpdateAsync(IList<AgentMessage> messages)
    {
        if (this.IsTerminated)
        {
            throw new TerminatedException();
        }

        // When operating as a conjunction, we may be accumulated terminating conditions, but we will not fire until
        // all of them are complete. In this case, we need to avoid continuing to interact with already terminated
        // clauses, because trying to update them will throw
        var candidateTerminations = this.conjunction ? this.clauses.Where(clause => !clause.IsTerminated) : clauses;

        // TODO: Do we really need these to be ValueTasks? (Alternatively: Do we really need to run them explicitly
        // on every invocation, or is a Worker pattern more appropriate?)
        List<Task<StopMessage?>> tasks = candidateTerminations.Select(c => c.CheckAndUpdateAsync(messages).AsTask()).ToList();
        StopMessage?[] results = await Task.WhenAll(tasks);

        bool raiseTermination = this.conjunction; // if or, we start with false until we observe a true
                                                  // if and, we start with true until we observe a false

        foreach (StopMessage? maybeStop in results)
        {
            if (maybeStop != null)
            {
                this.stopMessages.Add(maybeStop);
                if (!this.conjunction)
                {
                    // If any clause terminates, the disjunction terminates
                    raiseTermination = true;
                }
            }
            else if (this.conjunction)
            {
                // If any clause does not terminate, the conjunction does not terminate
                raiseTermination = false;
            }
        }

        if (raiseTermination)
        {
            this.IsTerminated = true;

            return new StopMessage
            {
                Content = string.Join("; ", stopMessages.Select(sm => sm.Content)),
                Source = string.Join(", ", stopMessages.Select(sm => sm.Source))
            };
        }

        return null;
    }
}