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 four 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, exactly four things travel: name, label, class and help keyword. 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, which is your decision and your code.

Can it modify my application?

Only through the actions you register, with the parameters you declared, and anything marked Confirm asks the user first. There is no generic entry point, and actions are off until you add at least one.

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. You can replace that instruction with Settings.Claude.SystemPrompt.

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. The demo has a checkbox that switches between the two at runtime.

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 ✕ 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?

Put one on the main form. The component registers a help viewer and watches the application's messages; two active instances would both answer F1.

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 FormCreate with Quick Start.
• Nothing opens: is Active True? is WebView2Loader.dll next to the executable?
• "Index: not found": Settings.DocIndexFile points nowhere — the demo shows the resolved path in its status bar.
• 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.