Providers
A provider is what turns the conversation plus the screen context into a reply. Which one is used is a string in the settings, so switching is a configuration change:
HelpChatAI.Settings.Provider := 'docsearch';Set it, like every line of Settings on this page, before the component is Active - or in helpchatai.json: the engine runs on a copy of the settings taken at activation (changing settings at runtime).
Five ship with the library. A provider registers itself when its unit is linked, so HelpChatAI.Provider.DocSearch, HelpChatAI.Provider.Claude, HelpChatAI.Provider.OpenAI or HelpChatAI.Provider.Gemini has to appear in a uses clause somewhere in the application. That holds with runtime packages too: a package runs the initialization of the units its host references, not of every unit it contains.
An unknown name is an error, not a fallback. A typo, or a provider whose unit nobody linked, used to answer with the placeholder of stub, which reads like a real reply and hides the mistake. Now the question comes back as an error bubble naming the provider you asked for, the unit to add and the providers actually available. Only an empty name means stub.
| Provider | Unit | Needs | Network | Streams | Actions |
|---|---|---|---|---|---|
stub | built in | nothing | no | no | no |
docsearch | HelpChatAI.Provider.DocSearch | the documentation index | no | no | no |
claude | HelpChatAI.Provider.Claude | ANTHROPIC_API_KEY | yes | yes | yes |
openai | HelpChatAI.Provider.OpenAI | OPENAI_API_KEY (not for a local server) | yes | yes | yes |
gemini | HelpChatAI.Provider.Gemini | GEMINI_API_KEY or GOOGLE_API_KEY | yes | yes | yes |
The three model providers answer the same way: your documentation is injected into the system prompt as grounding, the reply streams in token by token, and the assistant can call the actions your application registered.
To let the user choose among several providers or models - Claude, Gemini, a model on the user's own PC - list them as models: the panel then shows the icon of the one in use and switches from it. While a model of that list is in use, Settings.Provider reads as the provider of that model; Settings.ConfiguredProvider is the one the configuration names.
How the documentation reaches the model
Each excerpt enters the system prompt with its title, its summary, the passages around the words of the question and a source line that is already a Markdown link: Source: [Leads](Leads.md). The model is told to cite with that link copied as it is, never changed, completed or invented, to cite only the pages it used, and none when the documentation does not cover the question. Before 1.5.0 the line was a bare Leads.md and the instruction only said "cite its page link": every model cited in a form of its own - by title, in a footnote, with a URL it made up - and some listed pages at random under a question the manual does not answer. /search in the panel shows which pages an answer would be grounded on (commands).
The instruction improved every model, but an instruction is not a guarantee: with the same prompt Claude cited 8 answers out of 8 in one run of the benchmark and 6 out of 8 in the next, writing "according to the documentation" instead of the link. So the engine checks every reply of a model provider: when it links none of the pages the model was given, but names one of them by its title or its file name, the engine adds the line itself - Source: [Leads](Leads.md), in the language of the panel, streamed with the rest of the answer. It adds nothing when the model linked a page, when the answer names none (a question the documentation does not cover), and after an action. And it adds only a page the words of the question reach by themselves: the page of the screen the user is on helps the search, but it is not a source. Asked about the weather on the Dashboard, a model declines offering "what the Dashboard tiles count" - that is not an answer taken from the Dashboard page.
stub
The default. It answers with a localized placeholder, which is exactly what you want while you are wiring the component up: bubble, F1, panel, styles — everything works without any dependency.
docsearch
Deterministic, offline, free. It searches the documentation index with the question and the screen context, and replies with the title of the best page, its summary, a "read more" link, and a "see also" when a second page is close enough.
Perfect when:
- you cannot send anything outside the machine;
- you do not want to pay per question;
- your manual is good and the user mostly needs to be sent to the right page.
The retrieval is keyword scoring behind an interface (IHelpChatRetriever): tokens minus Italian and English stop words, light stemming, title hits ×6, keyword hits ×3, body hits capped, and idf weighting so that a word appearing in every page does not decide the ranking.
claude
Anthropic's Messages API, streaming, with your documentation injected as grounding: the retriever picks the pages that match the question and the screen, and their relevant passages are put in the system prompt. The model answers from those, cites the page, and says when it does not know — instead of inventing.
HelpChatAI.Settings.Provider := 'claude';
HelpChatAI.Settings.Claude.Model := 'claude-haiku-5-5';Claude.ApiVersion and Claude.PromptCaching are the only settings of its own; everything else is the common set.
The current Claude models think before they answer, unasked: a reply may begin with a thinking block, with no readable text and a signature. It is never part of the answer, and when the model calls actions it goes back to the API with their results, unchanged and in its place, as the API requires: without it the model starts every round of the loop from nothing. The thinking counts in MaxTokens.
The prompt cache. What a request repeats, the service keeps for five minutes and bills at a tenth of the price. claude keeps the system prompt the same for every question - now, the screen and the excerpts go with the question, in a message of their own - and marks the tools, the system prompt, the question and the rounds of the actions (Claude.PromptCaching, on by default): from the second question on, the tools, the rules and the whole conversation are read from the cache. Measured: 31% less input billed on the benchmark, answers unchanged. All of it, with what can make it miss: Prompt caching.
openai
Chat Completions, streaming, with the same grounding and the same tool use. It is the widest of the three, because a dozen other services chose to speak this API: BaseUrl and Model are all that separates them.
OpenAI itself is spoken to with the Responses API: there a reasoning model - the GPT-6 family, gpt-6-luna by default - keeps its reasoning while it runs the actions, which Chat Completions refuses. Nothing is kept on OpenAI's side (store: false): every request carries the conversation, and the encrypted reasoning of a step goes back with the results of its actions. A model that does not reason has none to give and says so: it is asked again without it, once, and remembered for as long as the application runs. OpenAI.Api forces one API or the other; every other service keeps Chat Completions. With a reasoning model the reasoning counts in MaxTokens: a reply that reaches it ends with a note saying it was cut - raise it if that happens to ordinary answers.
{
"OpenAI": { "ApiKey": "sk-..." },
"Models": [
{ "Name": "OpenAI", "Provider": "openai", "Model": "gpt-6.1-sol" },
{ "Name": "Gemma (local)", "Provider": "openai", "Model": "gemma4:12b",
"BaseUrl": "http://localhost:11434/v1" }
]
}The two live side by side: the first is OpenAI itself, through the Responses API and with the key of the section; the second has an endpoint of its own on this machine, so it goes through Chat Completions and never receives that key.
HelpChatAI.Settings.Provider := 'openai';
HelpChatAI.Settings.OpenAI.Model := 'gpt-6-luna';// Groq, OpenRouter, Mistral, DeepSeek, Together...
HelpChatAI.Settings.OpenAI.BaseUrl := 'https://api.groq.com/openai/v1';
HelpChatAI.Settings.OpenAI.Model := 'llama-3.3-70b-versatile';
// A model on the user's own machine: no key, nothing leaves the PC
HelpChatAI.Settings.OpenAI.BaseUrl := 'http://localhost:11434/v1'; // Ollama
HelpChatAI.Settings.OpenAI.Model := 'qwen2.5:7b';
// Azure OpenAI: the deployment is what changes the URL and the auth header
HelpChatAI.Settings.OpenAI.BaseUrl := 'https://my-resource.openai.azure.com';
HelpChatAI.Settings.OpenAI.AzureDeployment := 'my-gpt-deployment';With a BaseUrl of its own the section needs its key written for it - "OpenAI": {"ApiKey": ...} in a configuration file, see where the key goes: OPENAI_API_KEY is the key of api.openai.com and is not sent to another address.
| Setting | Default | What it does |
|---|---|---|
OpenAI.Organization | (empty) | OpenAI-Organization header; empty = not sent |
OpenAI.AzureDeployment | (empty) | Not empty = Azure: the deployment goes in the path and the key in the api-key header |
OpenAI.AzureApiVersion | 2024-10-21 | The api-version of Azure OpenAI |
OpenAI.Api | (empty) | responses or chat; empty = the Responses API on api.openai.com, Chat Completions anywhere else |
Three details that save an afternoon: a BaseUrl already ending in /v1 — what Ollama and LM Studio publish — is not given a second one; a missing key is reported for every endpoint on the internet, and only a server on this machine or on a private network (localhost, 127.x, 10.x, 172.16-31.x, 192.168.x, a .local name or a name with no dot) is spared, because it legitimately has none; and a reply that asks for an action is recognized by the call itself, not by the finish_reason, because Ollama, LM Studio and some gateways end such a turn with "stop".
The prompt cache. OpenAI caches the start of a request by itself, from 1,024 tokens on, and so does an Ollama on its own machine: the system prompt stays the same for every question, and now, the screen and the excerpts go with the question - in a developer message after it with the Responses API, in front of it with Chat Completions, which several local servers accept only as one message. Prompt caching.
Set this way, the endpoint is the one of the OpenAI section, and the key of the section goes with it. A model of the list that names a BaseUrl on another host is different: it gets no key unless it carries its own.
gemini
Google's streamGenerateContent, streaming, grounding and tool use as the others. The key travels in the x-goog-api-key header, never in the query string where it would end up in somebody's log.
HelpChatAI.Settings.Provider := 'gemini';
HelpChatAI.Settings.Gemini.Model := 'gemini-3.5-flash-lite';It takes the common settings and nothing else. Its implicit cache reads the start of a request again by itself, on long enough prompts: the system instruction stays the same for every question, and now, the screen and the excerpts are a second part of the question (prompt caching).
What every model provider takes
Settings.Claude, Settings.OpenAI and Settings.Gemini are the same shape, because in practice that is all a model needs. Each is read only when it is the section of the provider in use.
| Setting | Default | What it does |
|---|---|---|
ApiKey | (empty) | The key, in clear. Empty = the environment variable of that provider, while BaseUrl is the provider's own endpoint. Not published: it belongs to a file, or to code |
ApiKeyEncrypted | (empty) | The same key encrypted by your application; at run time it wins, through OnDecryptSecret |
Model | its own | Which model. Empty = the default of that provider, so you follow the library |
BaseUrl | its own | Empty = the official endpoint. This is what points a provider somewhere else |
MaxTokens | 4096 | Length of a reply. A reply cut at this limit says so at its end |
GroundingMaxPages | 3 | Documentation pages injected in the prompt |
GroundingMaxChars | 2000 | Characters of text per page (0 = summary only) |
MaxToolRounds | 4 | Model calls per reply when actions are used. With 1 the actions are not declared to the model at all |
ConnectTimeoutMs / ResponseTimeoutMs | 15 s / 120 s | Timeouts |
Defaults are claude-haiku-5-5, gpt-6-luna and gemini-3.5-flash-lite: the small, cheap models of each family, which for in-app help are the right ones — short answers, read from documents you already wrote. They are the ones the benchmark of the repository (Test\LLMBench, eight questions on the manual of the CRM demo, with actions) found best: every action right, the right pages cited, 1 to 2.5 seconds a reply. The larger models - Sonnet and Opus, gpt-6.1-sol, Gemini Pro and Gemini 4 - were as accurate on these questions and slower, up to 9 seconds for Gemini 4.
A reply that uses actions is a loop: the model asks, the application acts, the model is called again with the result, at most MaxToolRounds times. With MaxToolRounds = 1 there is no second call to tell the model how an action went, so none is offered to it. And when the last round still asks for an action, that action is not run: the reply ends with a note saying so, instead of reading as if it had been done.
Where the key goes
Never in your source code, never in a file you ship. The key of a section is what these leave in it, each one overwriting the one before when it names a key:
- the
ApiKeyof that provider's section, if you set it in code; %APPDATA%\HelpChatAI\helpchatai.json— shared by every HelpChatAI application of that user;helpchatai.jsonnext to the executable, then%APPDATA%\<YourApp>\helpchatai.json.
With no key there, the environment variable is read — ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY — but only while the endpoint is the service's own: the variable is named after the service, so a section whose BaseUrl points somewhere else (a local server, Groq, Azure OpenAI) never receives it, and says its key in ApiKey when it needs one. A model of the list that has a key of its own uses that one instead; one served by another host than the section's endpoint gets neither the key of the section nor the environment variable.
{
"Claude": { "ApiKey": "sk-ant-..." },
"OpenAI": { "ApiKey": "sk-..." },
"Gemini": { "ApiKey": "..." }
}Naming a file in ConfigFileName makes that one the whole configuration, and the list above does not apply.
On a desktop the key is on the user's machine and recoverable by whoever owns it. When that matters — an application installed at customers, or anything mobile — move the engine to a HelpChatAI server: the clients then authenticate with an application key that grants nothing but the right to ask questions.
The language of the assistant
HelpChatAI.Settings.Language := hclItalian; // hclAuto (default) follows the OS localeThe language sets the interface strings of the panel and is told to the model, which replies in that language whatever language the question is written in. Six languages are supported, the user may switch among them from the flag of the panel, and DocLanguage tells the model when the manual is written in another one: see Languages.
Writing your own provider
A provider is a class registered by name:
type
TMyProvider = class(THelpChatProviderBase)
public
function GetName: string; override;
function SupportsStreaming: Boolean; override;
function Generate(const AHistory: TArray<THelpChatMessage>;
const AContext: THelpChatContext; const AOnToken: THelpChatTokenProc;
const ACancel: IHelpChatCancelToken): string; override;
end;
initialization
THelpChatProviderRegistry.RegisterProvider('mine', TMyProvider);Inside Generate you have Settings (a private snapshot of the request), Retriever (the documentation index) and Actions. Two obligations: call AOnToken as tokens arrive if you say you stream, and check ACancel between steps — a user who stops a reply, or an application that is closing, must not wait for you.
You do not have to build the prompt yourself: BuildSystemPrompt already assembles the instruction, the language rule, the screen context and the documentation excerpts, the same way for everybody. If you stream, THelpChatSseStreamBase (HelpChatAI.Provider.Sse) does the byte-level half — chunks cut into lines, UTF-8 decoded only once a line is whole, one token at a time to the caller — and leaves you one method to write, ProcessLine.
Override ConfigurationIssue when your provider needs something to work, returning one sentence that says what is missing. That is what the design-time check and HelpChatAI.Diagnostics report: they ask the provider rather than knowing about it, so your provider is checked like the built-in ones.