Skip to content

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:

pascal
HelpChat.Settings.Skills := 'forms, commands, records, pages';

or in helpchatai.json, at the root or in the profile of one assistant:

json
{
  "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 ​

SkillActionsWhat the assistant can do
formsdescribe_form, fill_form, find_choice, cancel_editread 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
commandslist_commands, press_commandsee the buttons the user could press now and press one
recordscount_records, find_recordcount the records of a list and move it to the one the user names
pagesshow_pagebring 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:

pascal
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_form leaves the record in insert or edit and never calls Post; 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_edit and press_command go 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 AllowedActions lists 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 PasswordChar is described as filled or empty, never with its value, and find_record neither 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).
  • HideFieldValues hides what the fields hold, not the lists they choose from. With HelpChatVclSkills.HideFieldValues := True the model learns which fields are filled, never what they hold, and find_record reports no value. What still reaches it: the choices of a combo box, the codes and descriptions of a lookup table (describe_form lists up to thirty, find_choice searches the rest) and the filter of a list. Hide a field with OnDescribeField when 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:

HookWhat for
OnDescribeFieldEvery field before the model hears of it: correct its caption, mark it Required, add a description, or hide it (AAccept := False)
OnCommandEvery button: hide one, or offer one the skills took for a save (AAccept arrives False for those)
RegisterHelpChatVclFieldAdapter, RegisterHelpChatFmxFieldAdapterA kind of control the skills do not know: an adapter says whether it accepts a control, describes it, reads and writes its value
pascal
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:

pascal
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_page

When 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.

Released under the Apache License 2.0