| | | 1 | | using Microsoft.Extensions.AI; |
| | | 2 | | |
| | | 3 | | using NexusLabs.Needlr.AgentFramework.Diagnostics; |
| | | 4 | | |
| | | 5 | | namespace NexusLabs.Needlr.AgentFramework.Iterative; |
| | | 6 | | |
| | | 7 | | /// <summary> |
| | | 8 | | /// The result of running an <see cref="IIterativeAgentLoop"/> to completion, |
| | | 9 | | /// including per-iteration records, aggregate diagnostics, and the final model response. |
| | | 10 | | /// </summary> |
| | | 11 | | /// <remarks> |
| | | 12 | | /// <para> |
| | | 13 | | /// <see cref="Iterations"/> provides a complete trace of what happened in each iteration — |
| | | 14 | | /// which tools were called, what text was produced, and how many tokens were consumed. |
| | | 15 | | /// This is the primary diagnostic surface for understanding loop behavior and optimizing |
| | | 16 | | /// prompt factories. |
| | | 17 | | /// </para> |
| | | 18 | | /// </remarks> |
| | | 19 | | /// <param name="Iterations"> |
| | | 20 | | /// Per-iteration records in execution order. Always contains at least one entry. |
| | | 21 | | /// </param> |
| | | 22 | | /// <param name="FinalResponse"> |
| | | 23 | | /// The last <see cref="ChatResponse"/> produced by the model (preserving full message |
| | | 24 | | /// content, role, usage, and metadata), or <see langword="null"/> if the loop was |
| | | 25 | | /// terminated by <see cref="IterativeLoopOptions.MaxIterations"/>, |
| | | 26 | | /// <see cref="IterativeLoopOptions.IsComplete"/>, or cancellation before the model |
| | | 27 | | /// produced a response. Call <c>.Text</c> for a flat text view when evaluating. |
| | | 28 | | /// </param> |
| | | 29 | | /// <param name="Diagnostics"> |
| | | 30 | | /// Aggregate diagnostics for the entire loop run, including total token usage, |
| | | 31 | | /// all chat completions, and all tool calls. <see langword="null"/> if diagnostics |
| | | 32 | | /// were not enabled via <c>UsingDiagnostics()</c>. |
| | | 33 | | /// </param> |
| | | 34 | | /// <param name="Succeeded">Whether the loop completed without errors.</param> |
| | | 35 | | /// <param name="ErrorMessage"> |
| | | 36 | | /// The error message if the loop failed; <see langword="null"/> on success. |
| | | 37 | | /// Populated when the prompt factory throws, the loop is cancelled, or an |
| | | 38 | | /// unrecoverable LLM error occurs. |
| | | 39 | | /// </param> |
| | | 40 | | /// <param name="Termination"> |
| | | 41 | | /// Why the loop stopped. Use this instead of inspecting <see cref="Succeeded"/> |
| | | 42 | | /// and <see cref="ErrorMessage"/> separately — it provides a single discriminator |
| | | 43 | | /// for all termination paths. |
| | | 44 | | /// </param> |
| | | 45 | | /// <param name="Configuration"> |
| | | 46 | | /// Snapshot of the resolved configuration used for this run. Allows consumers |
| | | 47 | | /// to inspect mode, limits, and budget settings after execution without |
| | | 48 | | /// referencing the original <see cref="IterativeLoopOptions"/>. |
| | | 49 | | /// </param> |
| | 175 | 50 | | public sealed record IterativeLoopResult( |
| | 75 | 51 | | IReadOnlyList<IterationRecord> Iterations, |
| | 26 | 52 | | ChatResponse? FinalResponse, |
| | 133 | 53 | | IAgentRunDiagnostics? Diagnostics, |
| | 83 | 54 | | bool Succeeded, |
| | 35 | 55 | | string? ErrorMessage, |
| | 59 | 56 | | TerminationReason Termination, |
| | 190 | 57 | | IterativeLoopConfiguration Configuration); |