AIAssistant

TsgcHTMLAIAssistant: turns a question typed in plain language into a validated operation set for a grid, a data table, a pivot or a form, in Delphi, C++ Builder and .NET. It never touches your dataset, builds no SQL and emits no HTML.

TsgcHTMLAIAssistant

A non visual component. It turns a question into a closed set of operations, filters, sorts, a grouping, highlights and a limit for a grid, or rows, columns, a measure and an aggregate for a pivot, and the data component applies them to its own rows. A provider is optional: a built-in parser answers with no API key.

Component class

TsgcHTMLAIAssistant (unit sgcHTML_AI, non visual, a TsgcComponent_Base)

Renders

No markup: it returns validated operations, and the data components render them

Family

Chat & AI

Languages

Delphi, C++ Builder, .NET

Create it, assign it, route the query

Optionally configure a provider with Provider, APIKey and Model. Assign the assistant to the AIAssistant property of the data component, set AIQueryEnabled to render the query bar, and route the action the bar posts. You can also call the assistant directly.

uses
  sgcHTML_AI, sgcHTML_Component_Grid;

FAI := TsgcHTMLAIAssistant.Create(Self);
FAI.Provider := aiprOpenAI;
FAI.APIKey := 'API_KEY';   // optional, the built-in parser answers without it
FAI.Model := 'gpt-4o-mini';
FAI.AllowRowDataToProvider := False;   // the default

oGrid.AIAssistant := FAI;
oGrid.AIQueryEnabled := True;

// in the message handler, action = gridAIQuery
oGrid.LoadAIQueryState(vState);   // empty when the state lives in the session
oGrid.ProcessAIQuery(vQuery);
oGrid.LoadFromDataSource;         // when the grid is bound to a dataset
oHTMX.PushFragment(vGuid, oGrid.HTML);

// Or call it directly and read the validated operations
oCols := TsgcHTMLAIColumns.Create;
oOps := TsgcHTMLGridOps.Create;
try
  oCols.Add('Amount', aidtFloat, 'Order amount');
  oCols.Add('Country', aidtString).AddSample('Spain');
  oCols.Add('Date', aidtDate);
  if FAI.QueryToGridOps('amount greater than 500 sort by date desc',
    oCols, oOps) then
    vText := oOps.ToText;   // what survived validation, as text
finally
  oOps.Free;
  oCols.Free;
end;
// includes: sgcHTML_AI.hpp, sgcHTML_Component_Grid.hpp

FAI = new TsgcHTMLAIAssistant(this);
FAI->Provider = aiprOpenAI;
FAI->APIKey = "API_KEY";   // optional, the built-in parser answers without it
FAI->Model = "gpt-4o-mini";
FAI->AllowRowDataToProvider = false;   // the default

oGrid->AIAssistant = FAI;
oGrid->AIQueryEnabled = true;

// in the message handler, action = gridAIQuery
oGrid->LoadAIQueryState(vState);   // empty when the state lives in the session
oGrid->ProcessAIQuery(vQuery);
oGrid->LoadFromDataSource();       // when the grid is bound to a dataset
oHTMX->PushFragment(vGuid, oGrid->HTML);

// Or call it directly and read the validated operations
String vText;
TsgcHTMLAIColumns *oCols = new TsgcHTMLAIColumns();
TsgcHTMLGridOps *oOps = new TsgcHTMLGridOps();
try
{
  oCols->Add("Amount", aidtFloat, "Order amount");
  oCols->Add("Country", aidtString, "")->AddSample("Spain");
  oCols->Add("Date", aidtDate, "");
  if (FAI->QueryToGridOps("amount greater than 500 sort by date desc",
    oCols, oOps))
    vText = oOps->ToText();   // what survived validation, as text
}
__finally
{
  delete oOps;
  delete oCols;
}
using esegece.sgcWebSockets;

var ai = new TsgcHTMLAIAssistant();
ai.Provider = TsgcHTMLAIAssistant.TsgcHTMLAIProvider.aiprOpenAI;
ai.APIKey = "API_KEY";   // optional, the built-in parser answers without it
ai.Model = "gpt-4o-mini";
ai.AllowRowDataToProvider = false;   // the default

grid.AIAssistant = ai;
grid.AIQueryEnabled = true;

// in the message handler, action = gridAIQuery
grid.LoadAIQueryState(state);   // empty when the state lives in the session
grid.ProcessAIQuery(query);
grid.LoadFromDataSource();      // when the grid is bound to a dataset
htmx.PushFragment(guid, grid.HTML);

// Or call it directly and read the validated operations
var cols = new TsgcHTMLAIColumns();
var ops = new TsgcHTMLGridOps();
cols.Add("Amount", TsgcHTMLAIDataType.aidtFloat, "Order amount");
cols.Add("Country", TsgcHTMLAIDataType.aidtString).AddSample("Spain");
cols.Add("Date", TsgcHTMLAIDataType.aidtDate);
if (ai.QueryToGridOps("amount greater than 500 sort by date desc", cols, ops))
{
    string text = ops.ToText();   // what survived validation, as text
}

Key properties & methods

The members you reach for most often.

Editions and platforms

A provider needs the AI units of the Enterprise or All-Access edition, or the sgcAI pack, and they are Windows only. The built-in parser answers on every platform with no provider. The unit compiles when SGC_HTML is defined, which sgcVer.inc does not do for Android and iOS, and sgcHTML is a standalone pack, sold independently of sgcWebSockets.

Where to assign it

AIAssistant exists on TsgcHTMLComponent_Grid, TsgcHTMLComponent_DataTable, TsgcHTMLComponent_PivotTable, TsgcHTMLComponent_Form and TsgcHTMLComponent_InlineAIPrompt. AIQueryEnabled exists on the grid, the data table and the pivot: it renders the query bar, the interpreted-as chip and the clear control. The form has no AIQueryEnabled, it uses the assistant for smart paste, and InlineAIPrompt uses it for its answer. While no assistant is assigned, a grid renders no AI markup at all.

What leaves the machine

A grid or pivot question sends the column names, the captions, the types and up to three sample values per column, each cut to 40 characters. Nothing else, whatever the gate says. Rows leave only through the calls that are about rows, and only when AllowRowDataToProvider is True, which it is not by default: SuggestColumnValues and Summarize then return False and send nothing, and MaxRows caps what they may carry. Smart paste sends the text a person pasted and the name, label and type of each field, and no value of the form.

Validation is the boundary

Everything a provider returns is treated as hostile text. Every column name must match your whitelist, by exact name and without case. Every operator must be one of the 13 of TsgcHTMLAIOperator, every aggregate one of sum, count, avg, min and max, and every value is coerced by the type of its column: a value that does not coerce drops its whole operation. A highlight style must be one of primary, secondary, success, danger, warning, info, light or dark. Limits are clamped to MaxLimit, there are at most 32 filters, 32 sorts and 32 highlights, control characters are stripped, and anything unknown is discarded in silence. If nothing survives, the whole set is cleared, the explanation included. A prompt injection produces an empty or partial set, never an exception.

The operation model

TsgcHTMLGridOps holds Filters, Sorts, Highlights, GroupBy, Limit and Explanation. TsgcHTMLPivotOps holds Rows, Columns, Measure, Aggregate and Explanation. TsgcHTMLAIColumns is the whitelist: Add(aName, aDataType, aCaption) for each column, with AddSample for the samples. Both operation classes offer IsEmpty, ToText and ToJSON, and FromJSON is the full boundary only when you pass the columns, so revalidate anything read back from a browser against the live whitelist.

Choosing a provider

Provider is one of aiprOpenAI (the default), aiprAnthropic, aiprGemini, aiprDeepSeek, aiprOllama, aiprGrok and aiprMistral, the seven of TsgcAIChatProvider in sgcAI_Chat. Set APIKey or BaseUrl and the assistant owns a TsgcAI_Chat configured from Provider, APIKey, Model (empty keeps the chat default) and BaseUrl. Or assign your own chat component to Chat, which is only declared where the AI units are compiled in. Each call asks for structured output that follows a JSON schema, and your chat is restored afterwards. HasProvider tells which case you are in.

Rule-based fallback

With no provider the assistant answers with its own parser, and UseRuleBasedFallback (on by default) lets it answer a failed provider call as well. It reads clauses of the form column operator value joined by and or a comma, plus sort by, group by, top N, between A and B and highlight, and for a pivot the rows, the columns and the aggregate. It accepts the usual English spellings of each operator and either decimal separator. A question it does not understand produces no operation and the page keeps its rows. SuggestColumnValues and Summarize have no fallback.

SmartPaste for forms

SmartPaste(aText, aFields, aValues) maps pasted text onto a set of fields. Set SmartPasteEnabled on TsgcHTMLComponent_Form and it renders a paste zone; ProcessSmartPaste(aText) hands the text to the assistant, writes what came back into the fields by name and marks them as AI filled, with a small badge on the label. The rule-based parser answers it with no provider, and line breaks survive the trip to the server.

Column assistant

SuggestColumnValues(aPrompt, aRows, aValues) drives the grid column assistant. A column whose AIMode is not acOff renders a suggest control, ProcessAIColumnValues(aColumnName) asks for one value per visible row in a single call, and the answers become AIProposals with an Accept and a Reject control. The library writes nothing: an accepted proposal raises OnAIColumnValues and your application persists it. The call sends rows, so it needs a provider and AllowRowDataToProvider on.

Answer settings and events

Language sets the language of the free text, empty meaning the request locale. CacheMinutes (5) answers an identical question over an identical column set from the cache, and ClearCache empties it. MaxLimit (1000) cannot be raised above 1000. OnBeforeQuery(Sender, aPrompt, aAllow) sees the whole prompt before each provider call and blocks it when you set aAllow to False. No method raises: a provider failure reaches OnAIError(Sender, E, aHandled).

Host contract

There is no HTTP route. Each control is a data-sgc-ws-send form and your application dispatches on action: gridAIQuery, gridAIClear, gridAIColumn, gridAIAccept, gridAIReject, pivotAIQuery, pivotAIClear, formSmartPaste and the four actions of the inline prompt. Answer with the re-rendered component as an out of band fragment. One set of components is one user, so key them per session, and keep the authorization of what an action does on the server.

Keep exploring

Online HelpFull API reference and usage guide for this component.
AI Data Pack guideThe whole picture: what the model receives, validation, the rule-based parser, the host contract and the limits.
All sgcHTML ComponentsBrowse the full feature matrix of 80+ components.
Download Free TrialThe 30-day trial ships the 60.HTML demo projects, including 18.AIData, which asks a grid, a pivot and a form in plain language.
PricingSingle, Team and Site licenses with full source code.
Best value: All-AccessEvery eSeGeCe product, Premium Support included, from €1,059/year.
See All-Access pricing

Ready to Get Started?

Download the free trial and start building web UIs in Delphi, C++ Builder and .NET.