Skip to content

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 ​

PropertyTypeDefaultDescription
Profilestring(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
AssistantNamestring(empty)Public, in JSON only: the name of the assistant, which prevails over the component's AssistantName
Expertisestring(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
Instructionsstring(empty)What this assistant does in detail: added to the system prompt after the built-in rules, whatever model answers
SystemPromptstringHELPCHAT_MODEL_DEF_SYSTEMPROMPTThe 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
IdentityRulestringHELPCHAT_MODEL_DEF_IDENTITY_RULEThe opening sentence: %0:s the name of the assistant
NowRulestringHELPCHAT_MODEL_DEF_NOW_RULENow: %s the date, the time and the time zone; claude sends it with the question (prompt caching)
ExpertiseIntrostringHELPCHAT_MODEL_DEF_EXPERTISEWhat Expertise (%s) becomes in the prompt
ExpertiseRulestringHELPCHAT_MODEL_DEF_EXPERTISE_RULEAdded after the rules when there is an Expertise
LanguageRulestringHELPCHAT_MODEL_DEF_LANGUAGE_RULEThe language of the reply: %0:s the language of the chat, which decides whatever language the question is in
DocLanguageRulestringHELPCHAT_MODEL_DEF_DOC_LANGUAGE_RULEWhen DocLanguage differs from the chat's: %0:s the language of the manual, %1:s the chat's
SearchTermsPromptstringHELPCHAT_MODEL_DEF_SEARCH_TERMS_PROMPTThe system prompt of the request that translates the question for the search: %0:s the language of the manual. See Languages
ProviderstringstubWhich 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
LanguageTHelpChatLanguagehclAutoThe 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
LanguagesTHelpChatLanguagesall sixThe languages the user may pick from the flag; fewer than two = no flag. In JSON: an array of codes
DocLanguageTHelpChatLanguagehclAutoThe 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
TranslateSearchBooleantrueWhen 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
Greetingstring(localized)The first bubble of an empty conversation
PoolSizeInteger2Worker threads answering in parallel
LogLevelTHelpChatLogLevelllInfoHow much OnLogEvent receives: llNone, llInfo, llDetail, llDebug. In JSON "none", "info", "detail", "debug". See Logging
MessageMaxLengthInteger4000A longer user message is cut (0 = no limit)
HistoryMaxMessagesInteger50Messages sent to the provider as context (0 = all)
MaxStoredMessagesInteger200Messages kept in the store; older ones are pruned (0 = no limit)

Documentation ​

PropertyTypeDefaultDescription
DocIndexFilestringhelp-index.json next to the exeThe documentation index; a relative path is resolved against the executable
AllowedActionsstring(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
Skillsstring(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
DocAreasstring(empty)The areas of the manual this assistant knows, separated by commas; in JSON a string or an array. Empty = the whole manual
DocBaseUrlstring(empty)Prepended to the relative URLs of the pages
DocFolderstring(empty)Folder of Markdown pages the panel renders itself; see reading the pages inside the panel

Conversation persistence ​

PropertyTypeDefaultDescription
PersistConversationBooleanTrueSave and restore the conversation between runs
ConversationFilestring%APPDATA%\<App>\helpchatai-conversation[-<Profile>].jsonWhere. 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
ConversationMaxAgeDaysInteger30An 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.

PropertyTypeDefaultDescription
ApiKeystring(empty)The key in clear: what the IDE reads. Public, not published
ApiKeyEncryptedstring(empty)The same key encrypted by the application: wins at run time, through OnDecryptSecret (two nodes). Neither set = the environment variable of that provider
Modelstring(its own)Empty = the default model of that provider
BaseUrlstring(its own)Empty = the official endpoint
MaxTokensInteger4096Maximum length of a reply, the reasoning of the model included. A reply cut at it says so at its end
GroundingMaxPagesInteger3Documentation pages injected into the system prompt (0 = off)
GroundingMaxCharsInteger2000Characters of page text per page (0 = summary only)
MaxToolRoundsInteger4Model 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
ConnectTimeoutMsInteger15000
ResponseTimeoutMsInteger120000

Defaults per provider:

SectionModelEndpointEnvironment variable
Claudeclaude-haiku-5-5https://api.anthropic.comANTHROPIC_API_KEY
OpenAIgpt-6-lunahttps://api.openai.comOPENAI_API_KEY
Geminigemini-3.5-flash-litehttps://generativelanguage.googleapis.comGEMINI_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:

PropertySectionDefaultDescription
ApiVersionClaude2023-06-01anthropic-version header
PromptCachingClaudetrueMarks what repeats for the prompt cache of the service (prompt caching); false for a proxy that refuses cache_control
OrganizationOpenAI(empty)OpenAI-Organization header; empty = not sent
AzureDeploymentOpenAI(empty)Not empty = Azure OpenAI: deployment in the path, key in the api-key header
AzureApiVersionOpenAI2024-10-21The api-version query parameter of Azure
ApiOpenAI(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.

PropertyTypeDefaultDescription
SelectedModelstring(empty)The one in use; empty = the first of the list
ModelsTHelpChatModelEntries(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.

PropertyTypeDefaultDescription
BaseUrlstring(empty)Root URL of the HelpChatAI server. Empty = the engine runs in this process
AppKey / AppKeyEncryptedstring(empty)Key identifying this application to the server (not the model key). Public, not published: the two nodes of a secret
UserIdstring(empty)Who is asking, when the application knows: the server keeps one conversation per user
UserToken / UserTokenEncryptedstring(empty)Optional credential for UserId, validated by the server's OnAuthenticate. Two nodes, like every secret
UseHostChannelBooleanTrueOpen the loopback channel so the page can talk to its host (its ✕)
TimeoutMsInteger4000Timeout of the calls the transport makes on the UI thread

Attachments ​

Settings.Attachments — JSON object "Attachments". See Attaching documents.

PropertyTypeDefaultDescription
EnabledBooleanFalseShow the paper clip and accept what it sends. Off until you turn it on: an attachment leaves the machine
MaxCountInteger5Attachments a conversation may hold at a time (0 = no limit)
MaxSizeKBInteger8192Largest 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
MaxTotalKBInteger20480Largest 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.

PropertyTypeDefaultDescription
EnabledBooleanTrueThe buttons that save an answer, the conversation or a documentation page as PDF
ActionBooleanFalseRegister export_pdf, so the assistant can write a document and hand it over. One more tool in every request
PaperTHelpChatPdfPaperhcppA4hcppA4 or hcppLetter. In JSON: "A4", "Letter"
OrientationTHelpChatPdfOrientationhcpoPortraitIn JSON: "Portrait", "Landscape"
MarginMmInteger10The margin of the text, all four sides. A band is added to it, not taken out of it
PrintBackgroundsBooleanTrueOff, the shaded header row of a table comes out white
HeaderFooterBooleanFalsePrint the two bands - application and title above, user, date and page number below
BandMmInteger12How 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 ​

pascal
THelpChatSettings.SharedUserConfigFile;  // %APPDATA%\HelpChatAI\helpchatai.json
THelpChatSettings.AppConfigFile;         // helpchatai.json next to the executable
THelpChatSettings.UserConfigFile;        // %APPDATA%\<YourApp>\helpchatai.json

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

MethodDescription
Assign(Source)Copies every setting (this is how a request gets its private snapshot)
LoadFromJSON(AJson) / SaveToJSONRead 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
LoadFromDefaultFilesMerges 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) / ActiveModelThe section of a provider; the one in use, which is the Claude section for stub and docsearch
ResolveDocIndexFileThe index path actually used
ResolveConversationFileThe conversation path actually used
ResolveGreetingGreeting, or the localized default
ActiveModel.ResolveApiKeyThe 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.HasConfiguredApiKeyTrue 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 / NormalizedBaseUrlThe model and endpoint actually used, the override of the selected model included
ResolveModelsThe models with the model and endpoint each resolves to, the one in use marked; the implicit one of Provider when the list is empty
ActiveModelNameThe model in use
ApplyModel(AName)Makes it the one in use: Provider and the overrides of its section. False for an unknown name
ConfiguredProviderThe provider the configuration names, whatever the model in use put in Provider: what SaveToJSON writes
ResolveLanguageThe language the chat speaks, never hclAuto
ResolveDocFolder, ResolveDocAreas, ResolveAllowedActions, ResolveSkillsThe folder of the pages as a full path; the areas, the allowed actions and the skills as lists
ResolveSystemPromptThe field of expertise, SystemPrompt (or the library's rules), the rule of the expertise, then Instructions
ResolveIdentityRule, ResolveNowRule, ResolveLanguageRule, ResolveDocLanguageRuleThe 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.

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

Released under the Apache License 2.0