Skip to main content

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.

Naming

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​

ConcernMember(s)What it does
ToolsUsingAiToolsDeclare needed tool names — the base computes required AICapability and wires the session.
AI callsCallAIToolAsync(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 engineRunProcessingAsync(inputTree, processData, options, ct)Fans inputs out per branch, calls your callback with Dictionary<string,List<T>>, reassembles output trees.
Outputs/metricsFinishResults(name, tree, extra?)The output funnel — persists via GHPersistenceService + emits Metrics.
BatchTrySubmitBatchAsync(name, result, ct), SubmitBatchQueueAsync(ct), OnBatchCompleted(results, messages)Provider-batch collection and completion.
ProviderAIProviderComponentBase membersPer-component provider/model override, badge, Select AI Provider context menu.
Run policyRunOnlyOnInputChanges (base, default true)false → re-solve on provider/model change.
CustomizationPrepareInputs, SentinelTransformOutputs, SetAIReturnSnapshot, AppendAdditionalMenuItems, GetStateMessageVirtual 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​

FileOwns
.Main.csClass declaration, params registration (RegisterAdditional*Params), UsingAiTools, construction
.AI.csCallAIToolAsync, CallAIAsync, request parameters, batch interception
.Processing.csRunProcessingAsync, the ProcessData branch engine, PrepareInputs, SentinelTransformOutputs
.Batch.csTrySubmitBatchAsync, SubmitBatchQueueAsync, sentinel trees, OnBatchCompleted
.Metrics.csFinishResults, SetAIReturnSnapshot, metrics trees
.Persistence.csWrite/Read, RestorePersistentOutputs, menu items (Select AI Provider…)
.Lifecycle.csSolve lifecycle, debounce, RemovedFromDocument cleanup
.UI.csCreateAttributes, badges, GetStateMessage, selection/progress display

When not to use it​

  • Non-AI async work → AsyncComponentBase or StatefulComponentBase (you'd carry the AI badge/settings for nothing).
  • Input-adapter components (Input > output) → AIInputAdapterBase (a GH_Component, not stateful-async).
  • Selection-only UI → SelectingComponentBase / SelectingStatefulComponentBase.