| | | 1 | | using NexusLabs.Needlr.AgentFramework.Workspace; |
| | | 2 | | |
| | | 3 | | namespace NexusLabs.Needlr.AgentFramework.Iterative; |
| | | 4 | | |
| | | 5 | | /// <summary> |
| | | 6 | | /// Mutable state passed to the prompt factory and <see cref="IterativeLoopOptions.IsComplete"/> |
| | | 7 | | /// predicate on each iteration of an <see cref="IIterativeAgentLoop"/>. |
| | | 8 | | /// </summary> |
| | | 9 | | /// <remarks> |
| | | 10 | | /// <para> |
| | | 11 | | /// The prompt factory uses this context to build a state-aware prompt for each iteration. |
| | | 12 | | /// The workspace contains all persistent state (files written by tools); the prompt factory |
| | | 13 | | /// reads workspace files to understand what has been accomplished so far. |
| | | 14 | | /// </para> |
| | | 15 | | /// <para> |
| | | 16 | | /// <see cref="LastToolResults"/> contains tool results from the <em>previous</em> iteration |
| | | 17 | | /// only. They are ephemeral — cleared before each new iteration runs. The prompt factory |
| | | 18 | | /// can selectively embed them (e.g., search results) into the next prompt, or ignore them |
| | | 19 | | /// if the tool wrote its output to the workspace. |
| | | 20 | | /// </para> |
| | | 21 | | /// </remarks> |
| | | 22 | | public sealed class IterativeContext |
| | | 23 | | { |
| | | 24 | | /// <summary> |
| | | 25 | | /// Gets the zero-based iteration number. Incremented before each iteration runs. |
| | | 26 | | /// The prompt factory sees 0 on the first iteration, 1 on the second, etc. |
| | | 27 | | /// </summary> |
| | 183 | 28 | | public int Iteration { get; internal set; } |
| | | 29 | | |
| | | 30 | | /// <summary> |
| | | 31 | | /// Gets the workspace shared across all iterations. Tools read and write files here; |
| | | 32 | | /// the prompt factory reads files to build state-aware prompts. |
| | | 33 | | /// </summary> |
| | | 34 | | /// <remarks> |
| | | 35 | | /// The workspace is the primary memory mechanism for the iterative loop — it replaces |
| | | 36 | | /// conversation history accumulation. The loop does NOT manage workspace lifecycle; |
| | | 37 | | /// callers create and own the workspace instance. |
| | | 38 | | /// </remarks> |
| | 216 | 39 | | public required IWorkspace Workspace { get; init; } |
| | | 40 | | |
| | | 41 | | /// <summary> |
| | | 42 | | /// Gets the tool call results from the previous iteration, or an empty list on the |
| | | 43 | | /// first iteration. Results are ephemeral — they are replaced after each iteration. |
| | | 44 | | /// </summary> |
| | | 45 | | /// <remarks> |
| | | 46 | | /// <para> |
| | | 47 | | /// In <see cref="ToolResultMode.SingleCall"/> mode, these are the results of the tool |
| | | 48 | | /// calls the model requested (which were NOT sent back to the model). The prompt factory |
| | | 49 | | /// is responsible for embedding any relevant results into the next prompt. |
| | | 50 | | /// </para> |
| | | 51 | | /// <para> |
| | | 52 | | /// In <see cref="ToolResultMode.OneRoundTrip"/> mode, these are the results of any |
| | | 53 | | /// <em>second-round</em> tool calls (the model saw the first-round results and requested |
| | | 54 | | /// more tools, which were executed but not sent back). First-round results were already |
| | | 55 | | /// consumed by the model. |
| | | 56 | | /// </para> |
| | | 57 | | /// <para> |
| | | 58 | | /// In <see cref="ToolResultMode.MultiRound"/> mode, these are the results of tool calls |
| | | 59 | | /// from the final round that triggered the round limit. If the model produced a text |
| | | 60 | | /// response, this list is empty (no pending results). |
| | | 61 | | /// </para> |
| | | 62 | | /// </remarks> |
| | 363 | 63 | | public IReadOnlyList<ToolCallResult> LastToolResults { get; internal set; } = []; |
| | | 64 | | |
| | | 65 | | /// <summary> |
| | | 66 | | /// Gets a general-purpose state dictionary for passing arbitrary data between |
| | | 67 | | /// iterations. Callers can store anything here — counters, flags, intermediate |
| | | 68 | | /// computations — that doesn't belong in the workspace. |
| | | 69 | | /// </summary> |
| | 181 | 70 | | public IDictionary<string, object> State { get; } = new Dictionary<string, object>(); |
| | | 71 | | |
| | | 72 | | /// <summary> |
| | | 73 | | /// Gets the cancellation token for the current loop run. Tools and prompt factories |
| | | 74 | | /// should check this for cooperative cancellation. |
| | | 75 | | /// </summary> |
| | 125 | 76 | | public CancellationToken CancellationToken { get; internal set; } |
| | | 77 | | } |