Skip to content

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:

#FileMeant for
1%APPDATA%\HelpChatAI\helpchatai.jsonSettings shared by every HelpChatAI application of this user — typically the API key
2helpchatai.json next to the executableWhat the application ships or what IT deploys
3%APPDATA%\<YourApp>\helpchatai.jsonThis 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.

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

json
{
  "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).

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

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

SettingDefaultWhat it does
ProviderstubWhich provider answers
LanguagehclAutoInterface and reply language: auto (OS locale), en, it, es, fr, de, pt - see Languages
Languagesall sixThe languages the user may pick from the flag of the panel
DocLanguagehclAutoThe language of the documentation, when it differs from the chat's
Greeting(localized)The first bubble of an empty conversation
DocIndexFilehelp-index.json next to the exeThe documentation index
DocBaseUrl(empty)Prefix of the documentation links
PersistConversationTrueSave and restore the conversation between runs
ConversationMaxAgeDays30Older saved conversations are discarded
MaxStoredMessages200Kept in the store (older ones are pruned)
HistoryMaxMessages50Sent to the provider as context
MessageMaxLength4000A user message longer than this is cut
PoolSize2Worker 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.

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

FileWhereWhat
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.jsonnext to the conversationThe 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.

pascal
HelpChatAI.SelectModel('Gemma (local)');                 // what the panel does: next question uses it
HelpChatAI.Engine.Settings.Claude.MaxTokens := 2048;     // the running settings, while Active

Reading and writing the file from code ​

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

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

Released under the Apache License 2.0