The sample applications
What comes with the library is not a form with two buttons: it is the Windows 10 CRM demo that Embarcadero publishes, with HelpChatAI inside it and a manual of its own — in both frameworks. Everything on this page is in the repository and in the installer, under CRM Demo.
| Project | Delphi | What it is | |
|---|---|---|---|
| VCL | CRM Demo\VCL\project\VCL_CRMDemo.dproj | 10.4 → 13 | The whole application: the seven pages, the lead and proposal windows, all the actions |
| FMX | CRM Demo\FMX\project\FMX_CRMDemo.dproj | 12 → 13 | The same application over the same data: the FireMonkey half of the library in a real one |
They share one data module, one SQLite database, the actions of the assistant and one manual, in CRM Demo\common and CRM Demo\Help. Only the forms differ.
The database is not in the repository: the first start creates w10crmdemo.sdb in your Documents folder, encrypted, from the starting data the data module carries (uDataMod.dfm), and from then on the demos open that file - the leads and proposals you add while trying them stay there, for both demos. To start again from the original data, close the demos and run CRM Demo\ResetDemoDatabase.cmd: it deletes the file, and the next start creates it again. It refuses while a demo is running.
No key? It still runs
The applications work without an API key: the first run offers the License activation window described below; close it, and the assistant says the key is missing while everything else behaves as always. Select the docsearch provider and the same manual is searched offline; claude needs a key in %APPDATA%\HelpChatAI\helpchatai.json — see Providers.
The VCL one
CRM Demo\VCL\project\VCL_CRMDemo.dproj shows the VCL controls at work — the split view, the relative and card panels, the calendar view, LiveBindings over an encrypted FireDAC/SQLite database, the styles — and HelpChatAI answering about all of it.

The application is a small CRM: a dashboard of counters, a board of leads in four statuses, the accounts behind them, the proposals sent, a mailing list and a calendar.

Each screen has a page of the manual behind it, and the detail windows have one too — this is the one F1 opens from the lead detail:

It is in the repository for its manual: sixteen pages and seventeen screenshots in English, under CRM Demo\Help, written from the source of the application — the kind of documentation a real product actually has. Home.md is its first page and Index.md lists the rest, which is the shape the index builder likes.
The chat is in it, and it is the whole component: a TVclHelpChatAI on the main form, the claude provider grounded on that manual, and the actions below. F1 anywhere opens the assistant already asking about the screen in front of you, the round button in the corner opens it with no question, and asking it to do something makes it do it. The flag in the header switches the language of the chat: the application and its manual are in English (Settings.DocLanguage = hclEnglish), so in Italian or German the assistant explains in that language and keeps Save Proposal written as the button says.
| Ask it | What happens |
|---|---|
| "open the Marketing screen" | open_screen switches page. No confirmation: it changes nothing |
| "create a lead for James Carter of Zeus Red, Inc., phone 555 0142, email james.carter@example.com" | create_lead looks the company up in the Accounts list, asks, then creates the lead and opens its detail window |
| "create a lead for Dana Whitfield of Contoso Pharmaceuticals Ltd." (a company that is not there) | create_account asks to create the company first, then create_lead asks for the lead: two confirmations, and a No to the first ends there - the lead is not asked for |
| "prepare a proposal for Gary Orange: 12 hours of consulting at 150 each and 4 licenses at 480 each" | draft_proposal asks first, then fills the draft — customer, line items, total — and leaves Preview and Save Proposal to the user |
| "go to the Sales page", "how many accounts are there?", "change the phone of this lead to 555 0199" | The skills the demo names (Settings.Skills = 'forms, commands, records, pages'): show_page, count_records, describe_form and fill_form on whatever window is in front, with no action written for it |

Reading a document
Both demos accept attachments, and CRM Demo\Docs holds two files to try them with: a request for information as a PDF and the notes of the follow-up call. Attach the PDF and ask "create a lead from the attached request": the model reads the page, creates the company when it is not there yet and fills the create_lead call with what it found, one confirmation each. See Attaching documents.
Keeping an answer
Both demos ship with the PDF buttons and the export_pdf action on. Hover over an answer and two buttons appear beside it - copy and save; the same two at the top of the panel take the whole conversation. Or simply ask: "write me a PDF with a summary of what we said". The band at the top of every sheet reads the name and version out of the demo executable. See Saving and copying.
The key is not in clear
Neither demo keeps the API key as you typed it. When the model the assistant is about to use needs a key and has none, a License activation window opens - which is where a real application would ask its licensing service for it. It has a field for each service - Claude, Gemini, OpenAI, and a model of the catalogue on a service of its own (Groq, OpenRouter), whose key is that model's - and the one of the model in use is in bold ("Gemini (gemini-3.5-flash-lite) - the model in use"): the user types that key, and any other while at it. A field left empty changes nothing, and a service that has a key already says so.
- It opens at startup, for the model in use, and again whenever the user switches, in the panel, to a model that has no key (
OnModelChanged, readingRunSettings); - only when the provider of that model says a key is missing, the same check the configuration check makes:
docsearchand a local server onopenai(Ollama, LM Studio) never open it; - each key goes where the library will look for it: the section of the provider (
Claude,Gemini,OpenAI), or the entry of the catalogue when that model has an endpoint of its own - a key is never sent to another host than the one it is for.
What lands in the per-user helpchatai.json, as ApiKeyEncrypted, is AES-256 encrypted with DCPcrypt (CRM Demo\common\uAppSecret.pas; DCPcrypt is an svn:external used by the demos alone: no package of the library requires it). OnDecryptSecret is what reads it back, on the worker thread. Tools\ResetDemoKey.ps1 puts the demo back to "no key anywhere", to show it again. It is obfuscation and the unit says so in its first lines: see Security and privacy.
The log on file
Both demos write the log of the assistant to %APPDATA%\HelpChatAI\Logs\VCL_CRMDemo_<date>_<time>.log (FMX_CRMDemo_... for the FireMonkey one): each start appends to the last file, a new one begins at 5 MB, and five are kept. OnLogEvent hands each entry to CRM Demo\common\uHelpChatLog.pas, which writes it with Logify - its two units, Logify.pas and Logify.Adapter.Files.pas, are copied next to it with their MIT licence, the second with a class helper of TInterlocked for Delphi 10.4 and 11 ({$IF CompilerVersion <= 35}), whose TInterlocked has no Boolean overloads of Exchange and CompareExchange. The demos set Settings.LogLevel := llInfo; "LogLevel": "debug" in a helpchatai.json shows everything, question, reply and requests to the service included. See Logging.
What the integration is made of
In the order it matters:
| What | Where |
|---|---|
| The component, the provider and the index | HelpChat on the main form, its settings in the DFM: the provider, the index and the folder of the pages, the two languages, attachments, the PDF action and bands, MaxToolRounds = 6 |
| The key | Nothing in the application: Claude.ApiKey in %APPDATA%\HelpChatAI\helpchatai.json, the shared file every HelpChatAI application of that user reads first — or, with no key anywhere, the one the License activation window writes as ApiKeyEncrypted in the per-user file |
| The providers actually registered | HelpChatAI.Provider.DocSearch, .Claude, .OpenAI and .Gemini in the uses of uMainForm — a provider exists only if its unit is linked. With all four, every model of the configuration answers in the demo, and docsearch lets a helpchatai.json next to the executable take it offline without recompiling |
| Which page describes which screen | HelpType = htKeyword and HelpKeyword on the seven tab sheets and on the three windows |
| The screen when the focus is outside the page | OnGetContext forces the active tab when the screen is the main form (AContext.ScreenType): the side menu is not inside the TPageControl, so from there the chain would reach the form instead |
| What the assistant may do | RegisterCRMActions in common\uCRMActions, shared by both demos: four Actions.Add — open_screen with AConfirm = False, the three that write (create_account, create_lead, draft_proposal) asking first. The data is changed by the data module (CreateAccount, CreateLead, LeadForProposal); RegisterHelpActions in the main form passes only what a window does - open the tab, refresh the links, show the lead or the draft |
| The index | HelpIndexBuilder --source="CRM Demo\Help" --toc=Index.md, and the result versioned next to the manual |
Two of those rows are the ones to copy in your own application: point the builder at the folder of your manual and give your screens a HelpKeyword that matches the title of the page describing them; then register as actions the handful of things you are willing to let the assistant do, and let it ask before each one that writes.
Without a key it still opens
The assistant says the key is missing and the application works as always. Put { "Claude": { "ApiKey": "sk-ant-..." } } in %APPDATA%\HelpChatAI\helpchatai.json, or switch Settings.Provider to docsearch for the offline search on the same manual.
The copy in this repository is not quite the original: it fixes a crash on machines whose regional settings use the comma as decimal separator, and several size calculations that ignored the monitor scaling and left columns truncated at 150% or 175%. CRM Demo\Help\ToDo.md lists what was corrected and what is still open.
The FireMonkey one
CRM Demo\FMX\project\FMX_CRMDemo.dproj exists for one reason: until it was written, nobody had ever run the FireMonkey half of the library inside a real application. It is the whole application — the seven pages, the lead, proposal and proposal draft windows, the same bind sources of the same data module, and the same actions — with TFmxHelpChatAI on the main form and a HelpKeyword on every TTabItem. Delphi 12 and later, because TFmxHelpChatAI starts there.

It found two defects on its first run, and that is what a sample application is for:
- the FireMonkey bubble was placed outside the window the first time the form was resized. FireMonkey computes the anchor rules once, against the parent the control has at that moment, and the component was setting
AnchorsbeforeParent— so they were computed against a parent of size zero; - a relative
DocIndexFilewas resolved against the current directory instead of the executable, so the documentation index was found or not depending on who started the application. A shortcut, the IDE and Explorer set three different ones.
What FireMonkey does differently there is worth copying if you are porting something:
| VCL | FireMonkey |
|---|---|
TSplitView, CloseStyle = svcCompact | a docked TMultiView inside a layout whose width the button changes — see below |
TPageControl / TTabSheet | TTabControl / TTabItem, TabPosition = None |
TCardPanel / TCard | the same TTabControl without tabs |
TRelativePanel | Align plus margins, or a TVertScrollBox — the resize handlers of the VCL demo simply do not exist |
TTitleBarPanel | nothing: the two drop-downs go in a TToolBar |
TCalendarView | TCalendar |
TDateTimePicker with a blanked format | TDateEdit with IsEmpty |
MessageDlg returning the button | TDialogService.MessageDialog answering in a callback |
WebBrowser.Document.Write | TWebBrowser.LoadFromStrings |
TImageCollection + TVirtualImageList + TVirtualImage | one multi-resolution TImageList read by TGlyph |
VCL styles, linked by Custom_Styles | a .style file, loaded at run time — the demo ships the stock Dark of Delphi |
Three things that cost a run
F1 in a window that is not the host. The component chains the host form's OnKeyDown by itself; every other window asks it, which is what HandleKeyDown is for. The keyword cannot come from the form, because help properties live on TStyledControl and a form has none — so each unit declares its own as a constant and OnGetContext reads it from AContext.ScreenType, the form the component chose (Screen.ActiveForm is the chat itself when the user asks from it).
A date that is null must be asked of the field, not of the control. A null never reaches a TDateEdit as a zero: it leaves the control as it was, which is why all four dates of a new lead showed the date it was created. IsEmpty set from Field.IsNull or (Field.AsDateTime = 0) is the FireMonkey answer to the four OnAssignedValue handlers that blank the format of a VCL picker.
No mode of TMultiView is a TSplitView. Panel is permanent and hides the MasterButton you give it; Drawer and NavigationPane slide over the content and close again at the first click outside. A side menu that stays open until its button says otherwise is therefore a docked Panel inside a TLayout whose width the button changes — which is exactly what CloseStyle = svcCompact does. The icons of its items are TGlyph children of each TListBoxItem and not the item's ImageIndex, because that one is sized by the style of the TListBox and ignores how big the image is.
The multi-assistant edition
Both demos have a twin that shows several assistants in one application: VCL_CRMDemo_MultiAgent.dproj and FMX_CRMDemo_MultiAgent.dproj, next to the plain projects. They are the same forms and the same units, compiled with MULTIAGENT defined, into an executable and a DCU folder of their own (dcu\VCL-MultiAgent, dcu\FMX-MultiAgent: the same unit compiles differently in the two editions, so they must not share their DCUs). Start from the plain demo; open the twin when one assistant is clear.
Everything the edition adds is in one unit, uMultiAgent (uMultiAgentFmx in FireMonkey), plus two places of the main form under {$IFDEF MULTIAGENT}:
| The general assistant | The Sales assistant | |
|---|---|---|
| Where | the main window: the component of the form file | the lead window: created by CreateSalesAssistant, owned by that form, so its bubble, its window and its F1 are there |
| Profile | the default one | Sales: an engine and a conversation of its own |
| The manual | every page | DocAreas = Sales: the pages of the sales area and those of no area |
| Expertise | the one of the form file | B2B sales: proposals, pricing, discounts and VAT, follow-up |
| Actions | AllowedActions = open_screen, create_account, create_lead | AllowedActions = draft_proposal |
| Instructions | proposals are the Sales assistant's: send the user to the lead window | prepare and explain the proposals of the leads |
One action, two assistants, and the configuration decides. draft_proposal is registered once, in RegisterCRMActions like the others, but among the actions every assistant of the application may use (HelpChatSharedActions) instead of on the main component. Shared actions are offered to every assistant, so it is AllowedActions that narrows them: the general assistant's list leaves it out, the Sales assistant's names it. Ask the main window to prepare a proposal and it says that is the job of the Sales assistant; ask in the lead window and the draft opens after the confirmation. The handler does not know who called it, and the same keys could live under "Profiles" in helpchatai.json instead of in code.
The areas are in the front matter of the pages, so there is still one manual and one index for both editions:
---
areas: [Sales]
---
# LeadsSales holds Leads, Lead detail, Draft a proposal and Sales; General holds Accounts, Marketing, Users, Dashboard and Calendar; the pages every assistant needs - getting started, the FAQ, the assistant, the data model, the known limitations - have no area. The plain demo sets no DocAreas and reads every page, as before. An area has to be given to the pages the other assistant should not see, too: a page without one is everybody's, and an assistant narrowed to one area still reads all of those.
Building them from a command line
CRM Demo\BuildAllDemos.ps1 builds both, in both editions, with every Delphi it finds under C:\BDS\Studio, for Win32 and Win64, and prints a table of what passed:
.\BuildAllDemos.ps1 # the whole matrix, Release
.\BuildAllDemos.ps1 -Framework FMX -DelphiVersion D13
.\BuildAllDemos.ps1 -Edition Single # only the plain demos
.\BuildDemo.ps1 -Framework VCL -DelphiVersion D11 -Config Debug
.\BuildDemo.ps1 -Edition MultiAgent # the multi-assistant VCL demo
.\BuildDemoD10.4.ps1 # one version, the short wayA Delphi version that is not installed is reported as SKIP, and the FireMonkey demo below Delphi 12 as N/A — it is not a failure, the component does not exist there. Both demos compile the library from source, so nothing has to be installed in the IDE first.
The test suite
Not a demo, but worth knowing about: Test\Delphi13\HelpChatAITests.dproj is a DUnitX console suite of 616 tests covering the engine, the index scoring, the Markdown safety, the SSE parsing, the documentation pages, the profiles, the models and the slash commands, both transports over real HTTP on 127.0.0.1, and the actions from a real worker thread.
Test\Bin\Win32\HelpChatAITests.exe --exitbehavior:ContinueIt runs without network and without an API key.