Configuration
Every setting lives in Settings, a published property you can fill at design time, in code, or from a JSON file. The file is what lets an installed application be changed without a new build: the API key, the model, even moving the engine to a server.
helpchatai.json
With ConfigFileName empty (the default) the component merges, in this order, on activation:
| # | File | Meant for |
|---|---|---|
| 1 | %APPDATA%\HelpChatAI\helpchatai.json | Settings shared by every HelpChatAI application of this user — typically the API key |
| 2 | helpchatai.json next to the executable | What the application ships or what IT deploys |
| 3 | %APPDATA%\<YourApp>\helpchatai.json | This application, this user: wins over the others |
Only the keys present in a file are applied, so each file can carry just what it needs to change.
One file instead of three
Name a file in ConfigFileName and that file is the configuration: the three above are not read at all. A relative path is resolved against the executable.
HelpChatAI.ConfigFileName := 'config\helpchatai.json';A file named here and not found raises EHelpChatConfigError when the component activates. That is deliberate: an application that asked for a configuration and quietly runs without it is an application shipped with the wrong settings, and nobody finds out until a customer does.
{
"Provider": "claude",
"Language": "it",
"DocIndexFile": "help-index.json",
"DocBaseUrl": "https://help.mycompany.com/myapp/",
"Claude": {
"ApiKey": "sk-ant-...",
"Model": "claude-haiku-5-5",
"GroundingMaxPages": 3
}
}One section per model provider — Claude, OpenAI, Gemini — all with the same keys, plus the few that belong to one of them (Claude.ApiVersion, the OpenAI.Azure* trio). An empty Model or BaseUrl means the default of that provider, so a file that never mentions them keeps following the library. With no Models list only the section of Provider is read.
To let the user choose the model in the panel, add the models: the list names provider and model of each, the sections keep the keys and the endpoints they share, and SelectedModel says which one answers first. Provider then reads as the provider of the model in use; a model that names none runs on the one the configuration names (Settings.ConfiguredProvider).
{
"SelectedModel": "Claude",
"Models": [
{ "Name": "Claude", "Provider": "claude", "Model": "claude-haiku-5-5" },
{ "Name": "Gemma (local)", "Provider": "openai", "Model": "gemma4:12b" }
],
"Claude": { "ApiKey": "sk-ant-..." },
"OpenAI": { "BaseUrl": "http://localhost:11434/v1" }
}A file that names Models replaces the list of the files read before it, so the per-user file can narrow or widen what the application ships.
A key never follows a model to another host: a model whose BaseUrl is on another host than the endpoint of its section gets the key it carries itself, or none - never the key of the section, never the environment variable. A Groq or OpenRouter entry therefore needs its own BaseUrl and ApiKey; a local Ollama needs no key. See the key of a model.
One file, several assistants
An application with several assistants - an expert per form - keeps one configuration. Its root is what every assistant shares; "Profiles" holds, under the Profile of each component, what that assistant changes, with the same keys as the root:
{
"Claude": { "ApiKey": "sk-ant-..." },
"Instructions": "You are the assistant of the CRM.",
"Profiles": {
"Orders": {
"AssistantName": "Giulio",
"Expertise": "order management",
"Instructions": "Help the user enter orders.",
"DocIndexFile": "Help\\orders-index.json"
}
}
}Each file is applied root first and profile next, so within a file the profile wins; a later file wins over an earlier one, root or profile. A component whose profile is in no file reads the root alone - which is also what a misspelt Profile does, so the check of the component editor reports it as a warning.
In a profile, "Models" may list bare names: each is a model of the catalogue, the Models of the last root that had one. The catalogue is kept apart from the list a profile narrows it to, so the profile of a file read later can still name any model of it; a name it does not have raises EHelpChatConfigError.
The keys of 1.6 raise the same error instead of being ignored: Assistants is now Models, Assistant is now SelectedModel, and a SystemPrompt inside a provider section is now SystemPrompt or Instructions at the root or in a profile.
Never ship a file with a key in it
helpchatai.json is in the repository's ignore list for a reason, and the installer excludes it from what it packages. A key in an installer is a key on every customer's disk.
The settings that matter most
| Setting | Default | What it does |
|---|---|---|
Provider | stub | Which provider answers |
Language | hclAuto | Interface and reply language: auto (OS locale), en, it, es, fr, de, pt - see Languages |
Languages | all six | The languages the user may pick from the flag of the panel |
DocLanguage | hclAuto | The language of the documentation, when it differs from the chat's |
Greeting | (localized) | The first bubble of an empty conversation |
DocIndexFile | help-index.json next to the exe | The documentation index |
DocBaseUrl | (empty) | Prefix of the documentation links |
PersistConversation | True | Save and restore the conversation between runs |
ConversationMaxAgeDays | 30 | Older saved conversations are discarded |
MaxStoredMessages | 200 | Kept in the store (older ones are pruned) |
HistoryMaxMessages | 50 | Sent to the provider as context |
MessageMaxLength | 4000 | A user message longer than this is cut |
PoolSize | 2 | Worker threads answering in parallel |
The complete list, with the JSON key of every one of them, is in the Settings reference.
Checking a configuration
HelpChatAI.Diagnostics answers "would this work?" without sending a question: it reports the provider (registered? configured?), every model of the list, the documentation index, the folder of the pages, or the server when Settings.Remote names one. With a list of models the provider it checks is the one of the model in use, not the bare Provider; a finding about an entry of the list is filed under Model "<name>". DocAreas is compared with the areas the index has, and an area no page belongs to is a warning.
uses HelpChatAI.Diagnostics;
LIssues := HelpChatCheckSettings(HelpChat1.Settings);
if HelpChatHasErrors(LIssues) then
ShowMessage(HelpChatIssuesToText(LIssues));What a provider needs is the provider's own business: the check asks it through ConfigurationIssue instead of knowing about it, so a provider of yours is checked like the built-in ones. The same code runs behind Check configuration... in the component editor, which reads the files the application will read - the per-user one included - and behind /check in the panel.
Two more checks answer what the settings alone cannot. HelpChatCheckProfile(AProfile, AConfigFiles) warns when none of the files that were read has a section for the profile: the component editor calls it. HelpChatCheckActions(ASettings, AToolsJson) warns about each name of AllowedActions that no registered action answers to: only a running application knows its actions, so it is /check that calls it.
Where files are written
| File | Where | What |
|---|---|---|
helpchatai-conversation.json | %APPDATA%\<YourApp>\ | The saved conversation |
helpchatai-ui.json | %APPDATA%\<YourApp>\ | Position and size of the chat window, and where the bubble was dragged on each form |
helpchatai-state.json | next to the conversation | The model and the language the user picked in the panel |
WebView2\ | %APPDATA%\<YourApp>\ | The WebView2 user data folder of the VCL panel |
<YourApp>.exe.WebView2\ | %LOCALAPPDATA%\ | The WebView2 user data folder of the FireMonkey panel (the default of TWebBrowser), and of a PDF saved before any panel was opened |
An assistant with a Profile has the first three to itself, with the profile in the name: helpchatai-conversation-Orders.json, helpchatai-ui-Orders.json, helpchatai-state-Orders.json.
Nothing is written to the installation folder, so the application runs under a limited account.
Changing settings at runtime
The Settings of the component are what it starts with: at activation the configuration files are merged on top of them and a copy becomes the settings of the engine, which the assistants of the same profile share. Changing Settings while the component is active therefore affects the next activation. What runs is Engine.Settings, and that is also where the model and the language the user picks in the panel are written.
The settings of the engine are snapshotted per request: a provider works on a private copy, so a change while a reply is streaming does not corrupt it — it applies to the next message.
HelpChatAI.SelectModel('Gemma (local)'); // what the panel does: next question uses it
HelpChatAI.Engine.Settings.Claude.MaxTokens := 2048; // the running settings, while ActiveReading and writing the file from code
HelpChatAI.Settings.LoadFromFile('C:\Deploy\helpchatai.json');
HelpChatAI.Settings.SaveToFile(THelpChatSettings.UserConfigFile); // %APPDATA%\<YourApp>\THelpChatSettings.SharedUserConfigFile, AppConfigFile and UserConfigFile give you the three standard locations, so an "advanced settings" dialog of yours can write the right one. SaveToFile writes every setting of that one assistant, the API keys included, and no "Profiles": it is not a way to edit a file that several assistants share.
Moving the engine to a server
The same file decides where the engine runs:
{
"Remote": {
"BaseUrl": "https://help.acme.com",
"AppKey": "the-key-of-this-application",
"UserId": ""
}
}With a BaseUrl the component talks to a HelpChatAI server instead of running the engine in process — no recompilation, no code change.