AIStatefulAsyncComponentBase
The base class behind nearly every AI component in SmartHopper (AIChat, AIText2Text, AIScriptReview…). It lives in src/SmartHopper.Core/ComponentBase/ — split across partial files by concern — and turns a GH_Component into a stateful, provider-aware, async AI component with almost no boilerplate.
The current class is AIStatefulAsyncComponentBase (async + stateful). Older docs called it AIStatefulComponentBase/AIWorkerBase — those names and their GetResponse/ProcessAIResponse APIs were replaced by the AICall pipeline and AsyncWorkerBase.
Where it sits
GH_Component
└── AsyncComponentBase ← CreateWorker / async lifecycle
└── StatefulComponentBase ← run state machine, debounce, persistence,
│ RunOnlyOnInputChanges
└── AIProviderComponentBase ← provider/model selection + persistence,
│ Settings input
└── AIStatefulAsyncComponentBase ← THIS CLASS
├── AIOutputAdapterBase
└── AISelectingStatefulAsyncComponentBase
What it gives a component for free
| Concern | Member(s) | What it does |
|---|---|---|
| Tools | UsingAiTools | Declare needed tool names — the base computes required AICapability and wires the session. |
| AI calls | CallAIToolAsync(name, JObject, ct) | Run a tool through the managed pipeline; auto-intercepts into batch queue when the tool supports BuildRequest. |
CallAIAsync(AIBody, forceToolName, ct) | Escape hatch to run a raw request when tools aren't the shape you need. | |
| Tree engine | RunProcessingAsync(inputTree, processData, options, ct) | Fans inputs out per branch, calls your callback with Dictionary<string,List<T>>, reassembles output trees. |
| Outputs/metrics | FinishResults(name, tree, extra?) | The output funnel — persists via GHPersistenceService + emits Metrics. |
| Batch | TrySubmitBatchAsync(name, result, ct), SubmitBatchQueueAsync(ct), OnBatchCompleted(results, messages) | Provider-batch collection and completion. |
| Provider | AIProviderComponentBase members | Per-component provider/model override, badge, Select AI Provider context menu. |
| Run policy | RunOnlyOnInputChanges (base, default true) | false → re-solve on provider/model change. |
| Customization | PrepareInputs, SentinelTransformOutputs, SetAIReturnSnapshot, AppendAdditionalMenuItems, GetStateMessage | Virtual hooks. |
The contract you implement
Five members cover most components — see Components for a full worked example:
public override Guid ComponentGuid => …; // stable, unique
protected override IReadOnlyList<string> UsingAiTools => …; // tools you need
protected override void RegisterAdditionalInputParams(…); // your inputs
protected override void RegisterAdditionalOutputParams(…); // your outputs
protected override AsyncWorkerBase CreateWorker(Action<string>); // the worker
…plus a private AsyncWorkerBase subclass implementing GatherInput / DoWorkAsync / SetOutput. The base marshals phases: gather on the UI thread, work off-thread, outputs replayed by RestorePersistentOutputs.
Execution flow
The partial files
| File | Owns |
|---|---|
.Main.cs | Class declaration, params registration (RegisterAdditional*Params), UsingAiTools, construction |
.AI.cs | CallAIToolAsync, CallAIAsync, request parameters, batch interception |
.Processing.cs | RunProcessingAsync, the ProcessData branch engine, PrepareInputs, SentinelTransformOutputs |
.Batch.cs | TrySubmitBatchAsync, SubmitBatchQueueAsync, sentinel trees, OnBatchCompleted |
.Metrics.cs | FinishResults, SetAIReturnSnapshot, metrics trees |
.Persistence.cs | Write/Read, RestorePersistentOutputs, menu items (Select AI Provider…) |
.Lifecycle.cs | Solve lifecycle, debounce, RemovedFromDocument cleanup |
.UI.cs | CreateAttributes, badges, GetStateMessage, selection/progress display |
When not to use it
- Non-AI async work →
AsyncComponentBaseorStatefulComponentBase(you'd carry the AI badge/settings for nothing). - Input-adapter components (
Input >output) →AIInputAdapterBase(aGH_Component, not stateful-async). - Selection-only UI →
SelectingComponentBase/SelectingStatefulComponentBase.