Settings reference
THelpChatSettings (unit HelpChatAI.Settings) is the Settings property of both components and what helpchatai.json fills. Every property below has the same name as its JSON key.
Engine
| Property | Type | Default | Description |
|---|---|---|---|
Profile | string | (empty) | Public, not in JSON: the component's Profile, the section of "Profiles" applied on top of the root of each file, and the suffix of the conversation and state files. See Assistants |
AssistantName | string | (empty) | Public, in JSON only: the name of the assistant, which prevails over the component's AssistantName |
Expertise | string | (empty) | The field this assistant knows beyond the manual ("general accounting"): it opens the system prompt, with the rule that keeps the procedures of the application to the manual. See what an assistant knows |
Instructions | string | (empty) | What this assistant does in detail: added to the system prompt after the built-in rules, whatever model answers |
SystemPrompt | string | HELPCHAT_MODEL_DEF_SYSTEMPROMPT | The rules of the assistant: they carry the rules about excerpts and citations, so change them with care. Empty = the default. See the texts of the prompt |
IdentityRule | string | HELPCHAT_MODEL_DEF_IDENTITY_RULE | The opening sentence: %0:s the name of the assistant |
NowRule | string | HELPCHAT_MODEL_DEF_NOW_RULE | Now: %s the date, the time and the time zone; claude sends it with the question (prompt caching) |
ExpertiseIntro | string | HELPCHAT_MODEL_DEF_EXPERTISE | What Expertise (%s) becomes in the prompt |
ExpertiseRule | string | HELPCHAT_MODEL_DEF_EXPERTISE_RULE | Added after the rules when there is an Expertise |
LanguageRule | string | HELPCHAT_MODEL_DEF_LANGUAGE_RULE | The language of the reply: %0:s the language of the chat, which decides whatever language the question is in |
DocLanguageRule | string | HELPCHAT_MODEL_DEF_DOC_LANGUAGE_RULE | When DocLanguage differs from the chat's: %0:s the language of the manual, %1:s the chat's |
SearchTermsPrompt | string | HELPCHAT_MODEL_DEF_SEARCH_TERMS_PROMPT | The system prompt of the request that translates the question for the search: %0:s the language of the manual. See Languages |
Provider | string | stub | Which provider answers: stub, docsearch, claude, openai, gemini or one of yours. A name nobody registered is an error, not a fallback to stub. While a model of Models that names a provider is in use, it reads as the provider of that model; ConfiguredProvider is what the configuration says, and what a model with no provider of its own uses |
Language | THelpChatLanguage | hclAuto | The language of the chat: hclAuto (OS locale), hclEnglish, hclItalian, hclSpanish, hclFrench, hclGerman, hclPortuguese. In JSON: "auto" or the code ("en", "it", "es", "fr", "de", "pt"). See Languages |
Languages | THelpChatLanguages | all six | The languages the user may pick from the flag; fewer than two = no flag. In JSON: an array of codes |
DocLanguage | THelpChatLanguage | hclAuto | The language of the documentation: when it differs from the chat's, the model keeps the names of the screens and buttons as the manual writes them. hclAuto = not stated |
TranslateSearch | Boolean | true | When DocLanguage differs from the chat's, the model in use turns the question into search terms in the language of the manual before the search. See Languages |
Greeting | string | (localized) | The first bubble of an empty conversation |
PoolSize | Integer | 2 | Worker threads answering in parallel |
LogLevel | THelpChatLogLevel | llInfo | How much OnLogEvent receives: llNone, llInfo, llDetail, llDebug. In JSON "none", "info", "detail", "debug". See Logging |
MessageMaxLength | Integer | 4000 | A longer user message is cut (0 = no limit) |
HistoryMaxMessages | Integer | 50 | Messages sent to the provider as context (0 = all) |
MaxStoredMessages | Integer | 200 | Messages kept in the store; older ones are pruned (0 = no limit) |
Documentation
| Property | Type | Default | Description |
|---|---|---|---|
DocIndexFile | string | help-index.json next to the exe | The documentation index; a relative path is resolved against the executable |
AllowedActions | string | (empty) | The actions this assistant may use, own and shared, separated by commas; in JSON a string or an array. Empty = all of them. It narrows, never widens |
Skills | string | (empty) | The skills of this assistant, separated by commas: forms, commands, records, pages in the VCL, or one of yours; in JSON a string or an array. Naming a skill allows its actions, whatever AllowedActions says. Empty = none |
DocAreas | string | (empty) | The areas of the manual this assistant knows, separated by commas; in JSON a string or an array. Empty = the whole manual |
DocBaseUrl | string | (empty) | Prepended to the relative URLs of the pages |
DocFolder | string | (empty) | Folder of Markdown pages the panel renders itself; see reading the pages inside the panel |
Conversation persistence
| Property | Type | Default | Description |
|---|---|---|---|
PersistConversation | Boolean | True | Save and restore the conversation between runs |
ConversationFile | string | %APPDATA%\<App>\helpchatai-conversation[-<Profile>].json | Where. A relative path is resolved against the executable; a file named here is used as it is, so two profiles given the same name share it |
ConversationMaxAgeDays | Integer | 30 | An older saved conversation is discarded (0 = never) |
The model providers
Settings.Claude, Settings.OpenAI and Settings.Gemini — JSON objects "Claude", "OpenAI" and "Gemini". They are the same shape, and only the one of the provider in use is read: the one Provider names, or the one of the model picked in the panel. Settings.ActiveModel is that section, whichever it is.
| Property | Type | Default | Description |
|---|---|---|---|
ApiKey | string | (empty) | The key in clear: what the IDE reads. Public, not published |
ApiKeyEncrypted | string | (empty) | The same key encrypted by the application: wins at run time, through OnDecryptSecret (two nodes). Neither set = the environment variable of that provider |
Model | string | (its own) | Empty = the default model of that provider |
BaseUrl | string | (its own) | Empty = the official endpoint |
MaxTokens | Integer | 4096 | Maximum length of a reply, the reasoning of the model included. A reply cut at it says so at its end |
GroundingMaxPages | Integer | 3 | Documentation pages injected into the system prompt (0 = off) |
GroundingMaxChars | Integer | 2000 | Characters of page text per page (0 = summary only) |
MaxToolRounds | Integer | 4 | Model calls per reply when actions are used. With 1 no action is declared to the model: there would be no second call to tell it how the action went. An action still asked for in the last round is not run, and the reply ends with a note saying so |
ConnectTimeoutMs | Integer | 15000 | |
ResponseTimeoutMs | Integer | 120000 |
Defaults per provider:
| Section | Model | Endpoint | Environment variable |
|---|---|---|---|
Claude | claude-haiku-5-5 | https://api.anthropic.com | ANTHROPIC_API_KEY |
OpenAI | gpt-6-luna | https://api.openai.com | OPENAI_API_KEY |
Gemini | gemini-3.5-flash-lite | https://generativelanguage.googleapis.com | GEMINI_API_KEY, then GOOGLE_API_KEY |
The key of a section belongs to the service of that section. A model of Models that names a BaseUrl on another host (scheme, host or port) and no key of its own is called with no key at all: neither the one of the section nor the environment variable is sent to another address. See the key of a model. The environment variable itself is read only while the endpoint in force is on the scheme, host and port of the default one of the table above: a section whose BaseUrl points at another server gets the ApiKey written for it, never the variable.
And what belongs to one of them only:
| Property | Section | Default | Description |
|---|---|---|---|
ApiVersion | Claude | 2023-06-01 | anthropic-version header |
PromptCaching | Claude | true | Marks what repeats for the prompt cache of the service (prompt caching); false for a proxy that refuses cache_control |
Organization | OpenAI | (empty) | OpenAI-Organization header; empty = not sent |
AzureDeployment | OpenAI | (empty) | Not empty = Azure OpenAI: deployment in the path, key in the api-key header |
AzureApiVersion | OpenAI | 2024-10-21 | The api-version query parameter of Azure |
Api | OpenAI | (empty) | responses or chat. Empty = the Responses API on api.openai.com - where a reasoning model can use the actions without giving up its reasoning - and Chat Completions on every other endpoint (openai) |
Models
The models the user may switch between in the panel - see Assistants and models.
| Property | Type | Default | Description |
|---|---|---|---|
SelectedModel | string | (empty) | The one in use; empty = the first of the list |
Models | THelpChatModelEntries | (empty) | The list - JSON array "Models". A file that names it replaces it whole; in a profile an entry may be just the name of a model of the catalogue, which is the list of the last root that had one, in this file or in one read before it. A name the catalogue does not have raises EHelpChatConfigError. Empty = Provider alone, and no choice |
Each item (THelpChatModelEntry): Name, Provider, Model, BaseUrl, ApiKey, ApiKeyEncrypted, Icon. An empty Provider is the configured one; an empty Name becomes the provider and the model. Model, endpoint and key are empty when the provider's section already has the right ones; ApplyModel puts the ones it has on top of that section as overrides, which ResolveModel, NormalizedBaseUrl and ResolveApiKey read and SaveToJSON never writes. The two nodes of the key are not published, like every secret.
Profiles
"Profiles" (JSON only) is an object whose keys are profile names and whose values have the keys of the root. The profile of the settings is applied on top of the root of each file; see Assistants. SaveToJSON writes no "Profiles": what it saves are the settings of one assistant, already merged.
The keys of 1.6 are refused, not ignored: "Assistants", "Assistant" and a "SystemPrompt" inside a provider section raise EHelpChatConfigError, with a message that names the key to write instead ("Models", "SelectedModel", "SystemPrompt" or "Instructions" at the root or in a profile).
Remote engine
Settings.Remote — JSON object "Remote". See Running the engine on a server.
| Property | Type | Default | Description |
|---|---|---|---|
BaseUrl | string | (empty) | Root URL of the HelpChatAI server. Empty = the engine runs in this process |
AppKey / AppKeyEncrypted | string | (empty) | Key identifying this application to the server (not the model key). Public, not published: the two nodes of a secret |
UserId | string | (empty) | Who is asking, when the application knows: the server keeps one conversation per user |
UserToken / UserTokenEncrypted | string | (empty) | Optional credential for UserId, validated by the server's OnAuthenticate. Two nodes, like every secret |
UseHostChannel | Boolean | True | Open the loopback channel so the page can talk to its host (its ✕) |
TimeoutMs | Integer | 4000 | Timeout of the calls the transport makes on the UI thread |
Attachments
Settings.Attachments — JSON object "Attachments". See Attaching documents.
| Property | Type | Default | Description |
|---|---|---|---|
Enabled | Boolean | False | Show the paper clip and accept what it sends. Off until you turn it on: an attachment leaves the machine |
MaxCount | Integer | 5 | Attachments a conversation may hold at a time (0 = no limit) |
MaxSizeKB | Integer | 8192 | Largest single file; the page stops a bigger one before transferring it (0 = no limit). A picture never exceeds 3.6 MB, whatever is written here |
MaxTotalKB | Integer | 20480 | Largest total of a conversation (0 = no limit). Every attachment is sent again with every question |
Saving as PDF
Settings.Pdf — JSON object "Pdf". See Saving and copying.
| Property | Type | Default | Description |
|---|---|---|---|
Enabled | Boolean | True | The buttons that save an answer, the conversation or a documentation page as PDF |
Action | Boolean | False | Register export_pdf, so the assistant can write a document and hand it over. One more tool in every request |
Paper | THelpChatPdfPaper | hcppA4 | hcppA4 or hcppLetter. In JSON: "A4", "Letter" |
Orientation | THelpChatPdfOrientation | hcpoPortrait | In JSON: "Portrait", "Landscape" |
MarginMm | Integer | 10 | The margin of the text, all four sides. A band is added to it, not taken out of it |
PrintBackgrounds | Boolean | True | Off, the shaded header row of a table comes out white |
HeaderFooter | Boolean | False | Print the two bands - application and title above, user, date and page number below |
BandMm | Integer | 12 | How much room a band gets. What does not fit in it is cut |
The look of the document and what the bands say are not settings: they are files, named on the component in PdfStyleSheet, PdfHeaderFile and PdfFooterFile.
The configuration files
THelpChatSettings.SharedUserConfigFile; // %APPDATA%\HelpChatAI\helpchatai.json
THelpChatSettings.AppConfigFile; // helpchatai.json next to the executable
THelpChatSettings.UserConfigFile; // %APPDATA%\<YourApp>\helpchatai.jsonThey are merged in that order on activation when the component's ConfigFileName is empty — only the keys present in each file are applied. With a file named there, that one is read instead, and nothing else; if it is not found, activation raises EHelpChatConfigError. See Configuration.
Methods
| Method | Description |
|---|---|
Assign(Source) | Copies every setting (this is how a request gets its private snapshot) |
LoadFromJSON(AJson) / SaveToJSON | Read and write the JSON form. Reading applies only the keys present, the root and then the profile; writing gives every setting, the API keys included, with the configured provider and none of the overrides of the model in use |
LoadFromFile(AFileName) / SaveToFile(AFileName) | The same, on a file |
LoadFromDefaultFiles | Merges the three standard files; returns the ones it read |
LoadConfiguration(AFileName) | That file alone when named (raising if it is not there), else the three standard ones |
ModelFor(AProvider) / ActiveModel | The section of a provider; the one in use, which is the Claude section for stub and docsearch |
ResolveDocIndexFile | The index path actually used |
ResolveConversationFile | The conversation path actually used |
ResolveGreeting | Greeting, or the localized default |
ActiveModel.ResolveApiKey | The key actually used: the one of the model in use when it has one, else the one of the section (of the two nodes the encrypted one first, through OnDecryptSecret), else the environment variable. Empty for a model served by another host that brings no key |
ActiveModel.HasConfiguredApiKey | True when a key is configured, in either node |
SetSecretHandler(AHandler, ASender) | Installs the handler that decrypts the encrypted nodes (OnDecryptSecret), for code that has no component to publish it |
ActiveModel.ResolveModel / NormalizedBaseUrl | The model and endpoint actually used, the override of the selected model included |
ResolveModels | The models with the model and endpoint each resolves to, the one in use marked; the implicit one of Provider when the list is empty |
ActiveModelName | The model in use |
ApplyModel(AName) | Makes it the one in use: Provider and the overrides of its section. False for an unknown name |
ConfiguredProvider | The provider the configuration names, whatever the model in use put in Provider: what SaveToJSON writes |
ResolveLanguage | The language the chat speaks, never hclAuto |
ResolveDocFolder, ResolveDocAreas, ResolveAllowedActions, ResolveSkills | The folder of the pages as a full path; the areas, the allowed actions and the skills as lists |
ResolveSystemPrompt | The field of expertise, SystemPrompt (or the library's rules), the rule of the expertise, then Instructions |
ResolveIdentityRule, ResolveNowRule, ResolveLanguageRule, ResolveDocLanguageRule | The other texts of the prompt with their values; the library's text when one does not fit them |
SetPromptHandler(AHandler, ASender) | Installs OnBuildSystemPrompt for code that has no component to publish it |
ResolveStateFile, ProfileFileName(AFileName) | The files of this assistant, named after its profile |
A complete file
Every key SaveToJSON writes, with its default where it has one. "AssistantName" is written only when it is set, and the texts of the prompt ("SystemPrompt", "IdentityRule", "NowRule", "SearchTermsPrompt", "ExpertiseIntro", "ExpertiseRule", "LanguageRule", "DocLanguageRule") only when they differ from the library's; "Profiles" is read and never written.
{
"AssistantName": "",
"Expertise": "",
"Instructions": "",
"Provider": "claude",
"SelectedModel": "Claude",
"Models": [
{ "Name": "Claude", "Provider": "claude", "Model": "claude-haiku-5-5", "BaseUrl": "", "ApiKey": "", "ApiKeyEncrypted": "", "Icon": "" },
{ "Name": "Gemma (local)", "Provider": "openai", "Model": "gemma4:12b", "BaseUrl": "http://localhost:11434/v1", "ApiKey": "", "ApiKeyEncrypted": "", "Icon": "" }
],
"Language": "it",
"Languages": ["en", "it", "es", "fr", "de", "pt"],
"DocLanguage": "en",
"TranslateSearch": true,
"LogLevel": "info",
"Greeting": "",
"DocIndexFile": "help-index.json",
"DocAreas": "",
"AllowedActions": "",
"Skills": "",
"DocBaseUrl": "https://help.mycompany.com/myapp/",
"DocFolder": "Help",
"PoolSize": 2,
"MessageMaxLength": 4000,
"HistoryMaxMessages": 50,
"MaxStoredMessages": 200,
"PersistConversation": true,
"ConversationFile": "",
"ConversationMaxAgeDays": 30,
"Claude": {
"ApiKey": "",
"ApiKeyEncrypted": "",
"Model": "",
"MaxTokens": 4096,
"GroundingMaxPages": 3,
"GroundingMaxChars": 2000,
"MaxToolRounds": 4,
"BaseUrl": "",
"ApiVersion": "2023-06-01",
"PromptCaching": true,
"ConnectTimeoutMs": 15000,
"ResponseTimeoutMs": 120000
},
"OpenAI": {
"ApiKey": "",
"ApiKeyEncrypted": "",
"Model": "",
"BaseUrl": "",
"Organization": "",
"AzureDeployment": "",
"AzureApiVersion": "2024-10-21",
"Api": "",
"MaxTokens": 4096,
"GroundingMaxPages": 3,
"GroundingMaxChars": 2000,
"MaxToolRounds": 4,
"ConnectTimeoutMs": 15000,
"ResponseTimeoutMs": 120000
},
"Gemini": {
"ApiKey": "",
"ApiKeyEncrypted": "",
"Model": "",
"BaseUrl": "",
"MaxTokens": 4096,
"GroundingMaxPages": 3,
"GroundingMaxChars": 2000,
"MaxToolRounds": 4,
"ConnectTimeoutMs": 15000,
"ResponseTimeoutMs": 120000
},
"Remote": {
"BaseUrl": "",
"AppKey": "",
"AppKeyEncrypted": "",
"UserId": "",
"UserToken": "",
"UserTokenEncrypted": "",
"UseHostChannel": true,
"TimeoutMs": 4000
},
"Attachments": {
"Enabled": false,
"MaxCount": 5,
"MaxSizeKB": 8192,
"MaxTotalKB": 20480
},
"Pdf": {
"Enabled": true,
"Action": false,
"Paper": "A4",
"Orientation": "Portrait",
"MarginMm": 10,
"PrintBackgrounds": true,
"HeaderFooter": false,
"BandMm": 12
}
}