Skip to content

FAQ ​

Does it work without an API key? ​

Yes. The docsearch provider answers from your documentation index with no key and no network: it finds the right page, quotes its summary and links to it. The stub provider does not even need an index. A key is needed only by the model providers (claude, openai, gemini) - and not even by openai when you point it at a model running on the machine itself.

Where do I put the Anthropic API key? ​

In a JSON file on the machine, never in your source code or your installer: %APPDATA%\HelpChatAI\helpchatai.json with {"Claude": {"ApiKey": "sk-ant-..."}}. The environment variable ANTHROPIC_API_KEY works too. See Providers. If the key must not be on the user's machine at all, run the engine on a server.

Does my documentation have to be Markdown? ​

No. Markdown is what HelpIndexBuilder reads to build the index automatically, but the index is a plain JSON file: generate it from a CMS, a database of help topics, or an exported CHM. The format is a few fields per page — see The documentation index.

Does the chat need Internet? ​

Only the model providers do, and only towards the service you configured. The chat page itself is served by a local HTTP server bound to 127.0.0.1, and everything it needs — HTML, CSS, JavaScript, htmx — is compiled into the executable. No CDN, no external asset.

Which browser does it use? Do I have to install one? ​

WebView2 (Microsoft Edge) in the VCL and in FMX on Windows. The runtime is part of Windows 11 and of every machine with a recent Edge; what you ship is WebView2Loader.dll next to your executable. On macOS, iOS and Android, FMX uses the native web view of the platform.

Can the assistant see my data? ​

Only what you let it see. Of the screen, its label (or name) and its class travel; the help keyword only steers the search in the index. The conversation is what the user typed. Documentation excerpts come from your index. Nothing reads your database, your grids or your fields — unless you write an action that does, or name a skill in Settings.Skills: the skills read the fields of the window in front of the user and the records of its lists, and what they read reaches the model. Either is your decision.

Can the user keep an answer? ​

Yes, and it needs nothing from you. Every answer, the whole conversation and every documentation page carry two buttons: copy - the clipboard gets the text and the HTML, so a table pasted into Word is still a table - and save as PDF, which writes the document on the user's machine with the WebView2 runtime the panel already uses. Point PdfStyleSheet at a stylesheet of yours and turn on Settings.Pdf.HeaderFooter to get your application, the user, the date and the page number on every sheet. See Saving and copying.

Can the assistant read a document the user has? ​

Yes, once you turn it on: Settings.Attachments.Enabled := True puts a paper clip next to the question box, and a PDF, an image or a text file reaches the model with the question. Combined with an action, that is how a document fills a form without anybody retyping it. Word and Excel files are refused, because no model reads one - save as PDF, or export CSV. See Attaching documents.

Can it modify my application? ​

Only through the actions you register, with the parameters you declared, and the skills you name. An action of yours asks the user first unless you registered it with AConfirm = False; a skill asks before it writes or presses a button, not before it reads. There is no generic entry point, and the model is told of no action until you add one or name a skill.

The user asked something outside the manual: what happens? ​

With docsearch, the assistant says it found nothing and points at the documentation. With a model provider, the built-in system prompt tells it to answer from the documentation provided and to say when it does not know, instead of inventing. Settings.Expertise lets it explain what the manual takes for granted in its field - VAT, a pipeline, a follow-up - while the procedures still come from the manual (what an assistant knows); Settings.Instructions adds what your assistant does; Settings.SystemPrompt replaces the rules altogether.

My manual is in English: can the chat talk to the user in Italian? ​

Yes. The chat speaks six languages, the user picks one from the flag in the header, and Settings.DocLanguage = hclEnglish tells the model to explain in Italian while writing the names of buttons and screens as the manual and the application show them. See Languages - including how an Italian question finds the English pages: the model translates it for the search first (TranslateSearch).

Can I show the chat inside my own form instead of a separate window? ​

Yes, that is what Container and OnBeforeShowHelp are for: give the component any control — typically an alRight panel — and the chat fills it, like the assistant pane of recent Office versions. See Embedding the chat.

Does it block the UI while the model answers? ​

No. A model call runs on a worker thread; the reply streams into the panel token by token and can be stopped with the stop button (■) that takes the place of the send button. Closing the application while a reply is in flight is handled: the wait is bounded and a stuck worker is detached without touching freed memory.

Why is the panel a browser and not a Delphi form? ​

Because a conversation is text with formatting, links, code blocks and a growing partial reply — which is what HTML does well and what a TMemo does badly. It also means one implementation for VCL and FMX, and Markdown rendering for free. The cost is honest: WebView2 must be present, and the model's output must be treated as untrusted content (it is: safe-mode Markdown, restricted URL schemes, a Content-Security-Policy, and a browser confined to the panel origin).

Two chat components in one application? ​

Yes: one per form, if you like - a general assistant on the main form and an expert on the form of an important function. Each lives on the form that owns it, with its own bubble, and F1 goes to the assistant of the active form (on a form without one, to the one whose form was active last). One help viewer and one message hook serve them all. Two assistants on the same form work as well. See Assistants.

Can I change the look of the chat page? ​

The colours, yes and automatically: the panel follows your VCL style or the FMX ThemeMode, and OnGetTheme lets you override anything. The page itself is resources/panel.html|css|js, compiled into a resource by Tools\BuildResources.cmd: you can change it, keeping two rules — no hard-coded colours outside the --hc-* variables, and any new outbound call must be named in the page's Content-Security-Policy.

Which Delphi versions? ​

10.4 Sydney to 13 Florence for the engine and the VCL; 12 and 13 for FMX. Packages for each are built with each of those compilers, not only generated. See Installation.

Is it free? Can I use it in a commercial product? ​

Apache License 2.0: yes, including in closed-source commercial applications. The Ethea MarkdownProcessor, the one package the engine requires, keeps its own licence.

What does it cost to run? ​

stub and docsearch cost nothing, and so does a local model behind openai. With a hosted model you pay per question: each provider defaults to a small, fast one, and a reply is grounded on at most three documentation pages (GroundingMaxPages), so a typical question is a few thousand tokens. A server deployment lets you see and cap that centrally.

Does the conversation survive a restart? ​

Yes, by default (PersistConversation): it is saved in %APPDATA%\<YourApp>\ and reloaded if it is not older than ConversationMaxAgeDays (30). Set it to False for a kiosk or a shared machine.

Something is not working — where do I look? ​

  • The demo works and yours does not: compare your form with Quick Start.
  • Nothing opens: is Active True? is WebView2Loader.dll next to the executable?
  • The answers ignore the manual: Settings.DocIndexFile points nowhere. Type /check in the question box, or use the configuration check of the component editor at design time: both say which provider, key, index and pages folder are in force and what is missing.
  • Claude says it is not configured: the key is not in any of the places it is read from.
  • An answer is wrong or generic: it is usually the index, not the model. Check what docsearch finds for the same question from a console program.

Released under the Apache License 2.0