Skills: abilities by name
An action is something your application can do, and you write it: a name, a description, a handler. A skill is a set of actions the library has already written, about something every application has - its forms, their buttons, their lists, their pages - which an assistant gets by naming it:
HelpChat.Settings.Skills := 'forms, commands, records, pages';or in helpchatai.json, at the root or in the profile of one assistant:
{
"Skills": ["forms", "pages"],
"Profiles": {
"Sales": { "Skills": "forms, commands, records, pages" }
}
}Nothing is registered by hand and nothing is added to a uses clause: the skills come with Vcl.HelpChatAI and with FMX.HelpChatAI, the way a provider comes with its unit, and they work the same in both frameworks. With them the assistant stops telling the user where to type and does it - on the form they are looking at, with their confirmation, and without ever saving.
User: "fill in the contact: Mario Rossi, mario.rossi@acme.it, Lombardy, newsletter yes"
→ describe_form()
→ fill_form(values = {"edFirstName": "Mario", "edLastName": "Rossi",
"edEmail": "mario.rossi@acme.it", "cbRegion": "Lombardy",
"chkNewsletter": true},
mode = "current") [confirmed]
Assistant: "I filled the five fields of Contact. Nothing is saved yet: check them and
press Save."The four skills
| Skill | Actions | What the assistant can do |
|---|---|---|
forms | describe_form, fill_form, find_choice, cancel_edit | read the form the user is on - every field with its label, type, rules, value and description - and fill it, starting the insert or the edit of the record by itself |
commands | list_commands, press_command | see the buttons the user could press now and press one |
records | count_records, find_record | count the records of a list and move it to the one the user names |
pages | show_page | bring a tab of the form to the front, so that its fields can be read and filled |
Each page explains how the skill reasons: what it looks at, what it tells the model, what it refuses and why. They work together - show_page makes the fields of a tab visible to describe_form, find_record brings the record fill_form will edit - but each one can be enabled alone.
Which form
The skills work on the form the user is working on: the active form, unless it is the window of the chat or a dialog of the library; when the chat has the focus, the form that was active last (the VCL keeps that one first in Screen.CustomForms, FireMonkey announces it with TFormActivateMessage); for an MDI form of the VCL, its active child. That is also the form F1 was pressed on, so "fill this in" means what the user expects.
On that form they see what the user sees: the controls that are visible and enabled - and whose parents are, so the fields of a tab that is not shown are not there until show_page shows it - in tab order, the chat panel and the bubble left out.
An application that wants another target - a frame, a panel, a form that is not active - says so in OnGetTarget:
uses Vcl.HelpChatAI.Skills;
procedure TMainForm.FormCreate(Sender: TObject);
begin
HelpChatVclSkills.OnGetTarget := SkillTarget;
end;
procedure TMainForm.SkillTarget(Sender: TObject; var ATarget: TWinControl);
begin
if ATarget = Self then
ATarget := ActiveFrame; // the frame the user works in, not the whole main form
end;The rules they never break
- Nothing is saved.
fill_formleaves the record in insert or edit and never callsPost; a button that looks like it saves is never offered; a list whose record is being edited is never moved, because moving would post it. The user reviews and saves - which is also where the validation of your application runs, as it always did. - What changes something asks first.
fill_form,cancel_editandpress_commandgo through the confirmation of the component, with readable values - "First name: Mario", not a JSON object. Reading the form, counting, finding and showing a page change nothing the user cannot see, and do not ask. - Your actions win. An action your application registered with the same name as one of a skill - on the component or among the shared actions - is the one the model gets; the skill never replaces what the code wrote, and never takes it away.
- Naming a skill allows it. A profile whose
AllowedActionslists the actions of the code still gets the actions of the skills it names: the configuration that names a skill wants it. - A password is never read. An edit with a
PasswordCharis described as filled or empty, never with its value, andfind_recordneither searches nor reports the field behind it. That is told by the control: a password that is only a column of a grid is a field like any other, so keep it out of the grid (TField.Visible := False). HideFieldValueshides what the fields hold, not the lists they choose from. WithHelpChatVclSkills.HideFieldValues := Truethe model learns which fields are filled, never what they hold, andfind_recordreports no value. What still reaches it: the choices of a combo box, the codes and descriptions of a lookup table (describe_formlists up to thirty,find_choicesearches the rest) and the filter of a list. Hide a field withOnDescribeFieldwhen its lookup table is itself confidential.
Teaching them more
In the VCL the skills recognise edits, memos, masked and numeric edits, combo boxes, check boxes, radio groups and radio buttons, date pickers - and any data-aware control, of the VCL or of a third party, that publishes DataSource and DataField: the value goes through its TField - and, as in FireMonkey, any control bound by LiveBindings to a field. In FireMonkey, edits, number and spin boxes, memos, combo boxes and combo edits, check boxes and switches, radio buttons, date and time edits - and any control bound by LiveBindings to a field (see forms). Three hooks cover the rest, on HelpChatVclSkills and on its twin HelpChatFmxSkills:
| Hook | What for |
|---|---|
OnDescribeField | Every field before the model hears of it: correct its caption, mark it Required, add a description, or hide it (AAccept := False) |
OnCommand | Every button: hide one, or offer one the skills took for a save (AAccept arrives False for those) |
RegisterHelpChatVclFieldAdapter, RegisterHelpChatFmxFieldAdapter | A kind of control the skills do not know: an adapter says whether it accepts a control, describes it, reads and writes its value |
procedure TMainForm.DescribeField(Sender: TObject; const AField: THelpChatVclField;
var AAccept: Boolean);
begin
if AField.Id = 'edVatNumber' then
begin
AField.Required := True;
AField.Hint := 'Eleven digits, no country prefix.';
end
else if AField.Id = 'edInternalNotes' then
AAccept := False; // the assistant never sees it
end;HideFieldValues is one switch for both (HelpChatSkillsHideFieldValues). The functions behind every action are public too: HelpChatScreenDescribe, HelpChatScreenFill and the others of HelpChatAI.Skills.Screen take a screen - HelpChatFmxScreen(Form) in FireMonkey - and the VCL keeps HelpChatVclDescribeForm, HelpChatVclFillForm... on a control: an action of yours may call them on the form it chooses.
A skill of your own
A skill is a class registered by name, like a provider. Descend from THelpChatSkill (HelpChatAI.Skills), give it a name and a description, and add its actions in RegisterActions through AddAction, which keeps the rule above - an action the application already has is left alone:
type
TCalendarSkill = class(THelpChatSkill)
protected
procedure RegisterActions; override;
public
class function SkillName: string; override;
class function SkillDescription(const ALanguage: THelpChatLanguage = hclAuto): string; override;
end;
class function TCalendarSkill.SkillName: string;
begin
Result := 'calendar';
end;
class function TCalendarSkill.SkillDescription(const ALanguage: THelpChatLanguage): string;
begin
// What /skills shows the user; the built-in skills answer in the language asked.
Result := 'Reads and books the appointments of the user.';
end;
procedure TCalendarSkill.RegisterActions;
begin
AddAction('free_slots', 'Lists the free slots of the user in a day.',
[THelpChatActionParam.Create('day', 'The day, YYYY-MM-DD.')],
procedure(const AArgs: THelpChatActionArgs; var AResult: string)
begin
AResult := Agenda.FreeSlots(AArgs.AsString('day'));
end, False);
end;
initialization
HelpChatRegisterSkill(TCalendarSkill);One instance is created for each assistant that names it, when the assistant activates, and freed when it deactivates: a skill may keep state between the calls of its actions (forms keeps the previous values of what it filled, for cancel_edit). Supports(AHost) lets a VCL skill and a FireMonkey one share a name, each answering for its own component.
What the user sees
/skills in the question box lists the skills of the assistant - what each one does, in the language of the chat, and the actions it brings - and /actions lists those actions among the others, with their parameters:
Skills of the assistant (/skills):
- forms - Describes the window in front of you and fills its fields, asking first and never saving.
describe_form, fill_form, find_choice, cancel_edit
- pages - Brings a page (a tab) of the window to the front.
show_pageWhen a name does nothing
A name nobody registered - a typo, a skill of a unit the application does not link - is skipped: an application must start whatever its configuration says. /skills marks it not available in this application, and the configuration check and /check report it as a warning, with the names that exist.
One set of rules, two frameworks
The four skills are written once, in HelpChatAI.Skills.Screen (RTL and Data.DB, in the engine package): what the model is told, how a value is read, when a data set goes into insert or edit, the rule that nothing is ever saved. What a framework gives them is a screen - the form the user is on, seen as fields, lists, pages and buttons - through a THelpChatScreenProvider it registers: Vcl.HelpChatAI.Skills over the controls of the VCL, FMX.HelpChatAI.Skills over those of FireMonkey and their LiveBindings. So the same question gets the same answer in both, in the same words; and a framework of your own (a grid library with its own editors, a web of frames) is one more provider.