Package com.chilkatsoft.chilkat2

Class Ai

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Ai
All Implemented Interfaces:
AutoCloseable
public class Ai extends ChilkatObject
<section class="ai-summary">

Use one consistent API for multiple AI providers.

Chilkat.Ai provides a unified interface for sending prompts, multimodal input, conversations, streaming requests, tool calls, and file references to many AI providers. Instead of writing separate REST integrations for each vendor, applications can use one Chilkat API while Chilkat handles provider-specific differences in authentication, request formatting, response parsing, streaming events, and tool-calling workflows.

OpenAI Google Gemini Anthropic Claude xAI Grok Mistral DeepSeek Perplexity Custom Providers

Portable provider access

Write code once and switch providers by changing settings such as Provider, Model, ApiKey, BaseUrl, and ApiSpec.

Conversations

Create, select, export, import, list, and delete named conversations. Chilkat can maintain local transcripts or use provider-hosted conversation state where supported.

Multimodal input

Add text, image data, image URLs, file data, file URLs, and uploaded file references to the next request.

Streaming responses

Use Streaming, PollAi, and NextAiEvent to receive incremental output and standardized streaming events.

Tool calling

Supports manual function tool calling and automatic JavaScript tool calling, including safeguards such as tool timeouts and iteration limits.

File upload and reuse

Upload files once, receive a file ID or URI, and reference that file in later requests when supported by the provider.

Starting in v11.4.0: Chilkat.Ai adds manual tool function calling, automatic JavaScript tool calling, file uploads for later reference by file ID, and conversational image output for providers that support it.

AI responses are often returned as Markdown. Chilkat also provides Markdown to HTML support in the StringBuilder class, including streaming Markdown-to-HTML conversion for applications that display AI output as it is generated.

Also see Markdown to HTML Overview. For an extended overview, see Ai Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Ai

      public Ai()
      Creates a new Ai object.

  • Method Details

    • getApiKey

      public String getApiKey()
      This is the API key used for authentication. Use your API key that matches your getProvider() .

      Suggestion: Use Chilkat's Secrets class to store and retrieve API keys in any of the following locations.

      • Windows Credentials Manager
      • Apple Keychain
      • AWS Secrets Manager
      • Azure Key Vault
      • IBM Cloud Secrets Manager
      • Oracle Cloud Secrets
      • Doppler Secrets
      Returns:
      the value of the ApiKey property

    • setApiKey

      public void setApiKey​(String value)
      Sets the ApiKey property; see getApiKey().
      Parameters:
      value - the new value (not null)

    • getApiKeyHeader

      public String getApiKeyHeader()
      For custom getProvider()'s, use this field name for the API key in the HTTP header, but only if the API key is to be placed in a custom header field. If the API key is to be provided in an "Authorization: Bearer" header, then leave this property empty.

      The default value of this property is the empty string.

      Returns:
      the value of the ApiKeyHeader property

    • setApiKeyHeader

      public void setApiKeyHeader​(String value)
      Sets the ApiKeyHeader property; see getApiKeyHeader().
      Parameters:
      value - the new value (not null)

    • getApiSpec

      public String getApiSpec()
      Specifies the API specification to be used. Possible choices are ChatCompletions, Responses, Gemini, Anthropic. The default value is Responses because the default value of the getProvider() property is openai. Setting the getProvider() property to a value other than custom will also automatically set this property to the correct and needed value.
      Returns:
      the value of the ApiSpec property

    • setApiSpec

      public void setApiSpec​(String value)
      Sets the ApiSpec property; see getApiSpec().
      Parameters:
      value - the new value (not null)

    • getBaseUrl

      public String getBaseUrl()
      Specifies the provider's base URL. For example, http://localhost:11434/v1 or https://api.together.xyz/v1. The default value is https://api.openai.com/v1 because the default value of the getProvider() property is openai. Setting the getProvider() property to a value other than custom will also automatically set this property to the correct and needed value.
      Returns:
      the value of the BaseUrl property

    • setBaseUrl

      public void setBaseUrl​(String value)
      Sets the BaseUrl property; see getBaseUrl().
      Parameters:
      value - the new value (not null)

    • getEnableSecrets

      public boolean getEnableSecrets()
      If true a secret specifier of the format "!!part1|part2|.." can be provided instead of the actual value for the ApiKey property.

      The default value is false.

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

      public void setEnableSecrets​(boolean value)
      Sets the EnableSecrets property; see getEnableSecrets().
      Parameters:
      value - the new value

    • getFullTranscript

      public boolean getFullTranscript()
      For multimodal inputs like image data, image URLs, file data, and file URLs, the full data or URL is sent initially. If the property is set to true, the full data/URL is re-sent in subsequent interactions. If set to false, only the image or file summary is sent thereafter.

      By default, this property is false.

      Full transcript style: always send the entire conversation (including files/images). This guarantees the model has all context, but can get expensive.

      Summarized transcript style: for previously sent multimodal items, sends the summary message (e.g. “Earlier, I uploaded a PDF with account statements”) instead of the raw file or url itself.

      Returns:
      the value of the FullTranscript property

    • setFullTranscript

      public void setFullTranscript​(boolean value)
      Sets the FullTranscript property; see getFullTranscript().
      Parameters:
      value - the new value

    • getHasFunctionCalls

      public boolean getHasFunctionCalls()
      true if the response output has function calls. Otherwise false. This only applies to manual function tool calling, not automatic JS tool calls.
      Returns:
      the value of the HasFunctionCalls property (read-only)

    • getHeartbeatMs

      public int getHeartbeatMs()
      The interval in milliseconds between each AbortCheck event callback, which enables an application to abort certain method calls before they complete. By default, HeartbeatMs is set to 0, meaning no AbortCheck event callbacks will trigger.
      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getHostedConvo

      public boolean getHostedConvo()
      This applies to providers like OpenAI that can maintain conversation state on the server. If set to true, only the conversation ID is sent with each query. If set to false, the entire conversation transcript is sent with each query, making each query stateless.

      This only applies if a conversation is selected.

      The default value of this property is false.

      Returns:
      the value of the HostedConvo property

    • setHostedConvo

      public void setHostedConvo​(boolean value)
      Sets the HostedConvo property; see getHostedConvo().
      Parameters:
      value - the new value

    • getIdleTimeoutMs

      public int getIdleTimeoutMs()
      The maximum amount of time to wait for additional incoming data when receiving a response. The default value is 90000 (90 seconds) in v11.3.0 and earlier. Starting in v11.4.0, the default value is 180000 (180 seconds).

      This is not a total timeout, but the maximum time allowed when data transmission has paused.

      Returns:
      the value of the IdleTimeoutMs property

    • setIdleTimeoutMs

      public void setIdleTimeoutMs​(int value)
      Sets the IdleTimeoutMs property; see getIdleTimeoutMs().
      Parameters:
      value - the new value

    • getJsToolTimeout

      public int getJsToolTimeout()
      The maximum time in seconds allowed for an automatic JavaScript tool function. The default value is 60 seconds to allow for most use cases, but to prevent an tool call that never returns.
      Returns:
      the value of the JsToolTimeout property

    • setJsToolTimeout

      public void setJsToolTimeout​(int value)
      Sets the JsToolTimeout property; see getJsToolTimeout().
      Parameters:
      value - the new value

    • getLastResponseRefused

      public boolean getLastResponseRefused()
      Read-only. true if the model refused to produce the requested structured output during the most recent ask(String). When a refusal occurs, getOutputJson(JsonObject) returns false and the provider's explanation is available in getRefusalText() . This property is reset at the start of each ask(String).
      Returns:
      the value of the LastResponseRefused property (read-only)

    • getModel

      public String getModel()
      The model to be used for AI conversations. For example, GPT-4o or GPT-5. The list of available models can be obtained by calling getModels(StringTable).

      The default value is the empty string. A model must always be specified. Chilkat won't try to guess or default to a model.

      Returns:
      the value of the Model property

    • setModel

      public void setModel​(String value)
      Sets the Model property; see getModel().
      Parameters:
      value - the new value (not null)

    • getProvider

      public String getProvider()
      This is the AI provider. Possible values are: openai, google, claude, deepseek, perplexity, mistral, and xai.

      Starting in Chilkat v11.3.0, this property can be set to custom, and the getBaseUrl() and getApiSpec() properties can also be set to fully specify the provider.

      Starting in v11.6.0, this property can also be set to openai-compatible, a convenience alias for a custom provider that speaks the OpenAI Chat Completions API. It presets getApiSpec() to ChatCompletions, so you only need to set getBaseUrl() (plus getApiKey() and getModel()). This is the simplest way to use OpenAI-compatible endpoints such as Ollama, LM Studio, OpenWebUI, and many hosting providers.

      Note: mistral is recognized as a pre-configured known provider starting in v11.4.0.

      The default value is openai.

      Returns:
      the value of the Provider property

    • setProvider

      public void setProvider​(String value)
      Sets the Provider property; see getProvider().
      Parameters:
      value - the new value (not null)

    • getRefusalText

      public String getRefusalText()
      Read-only. When getLastResponseRefused() is true, this is the model's message explaining why it declined to produce the requested structured output. Otherwise it is the empty string.
      Returns:
      the value of the RefusalText property (read-only)

    • getResponseStatusCode

      public int getResponseStatusCode()
      The HTTP response status code for the last ask(String) is as follows:
      • 0 indicates an error occurred before receiving an HTTP response.
      • 200 indicates a successful response.
      • A failed response has a status code of 400 or higher.

      Returns:
      the value of the ResponseStatusCode property (read-only)

    • getSelectedConvo

      public String getSelectedConvo()
      The currently selected conversation can be set to your desired conversation name. Once set, all future queries will be part of that conversation, updating its state with each input and output. By default, no conversation is selected, indicated by an empty string, leading to stateless queries. The first conversation created or imported will be automatically selected. If you attempt to select a non-existent conversation, the selection will not change. You can reset this property to an empty string to revert to stateless querying.
      Returns:
      the value of the SelectedConvo property

    • setSelectedConvo

      public void setSelectedConvo​(String value)
      Sets the SelectedConvo property; see getSelectedConvo().
      Parameters:
      value - the new value (not null)

    • getStreaming

      public boolean getStreaming()
      When set to true, the ask(String) method operates in streaming mode, returning immediately after the request is sent. You can then use the PollAi and NextAiEvent methods to receive streaming events. By default, this property is false.
      Returns:
      the value of the Streaming property

    • setStreaming

      public void setStreaming​(boolean value)
      Sets the Streaming property; see getStreaming().
      Parameters:
      value - the new value

    • getUncommonOptions

      public String getUncommonOptions()
      This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.
      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • ask

      public void ask​(String outputType)
      Sends the current potentially multimodal input within the context of the selected conversation and receives the model's output. Prior to v11.4.0 the outputType is limited to text. Starting in v11.4.0, the outputType can be set to image for AI providers that support conversational image output.

      Accumulated outputs are cleared on entry to this method. Accumulated inputs are cleared on the successful return of this method.

      This method cannot be called while a streaming Ask is in progress. In such a case the return value is false and nothing will occur.

      Parameters:
      outputType - the outputType argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • deleteConvo

      public void deleteConvo​(String name)
      Deletes the conversation by its name. If name equals * then all conversations are deleted.
      Parameters:
      name - the name argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • exportConvo

      public void exportConvo​(String name, JsonObject json)
      Exports the conversation specified by name to json, replacing json's contents with the exported transcript. You can later import a conversation using importConvo(String, JsonObject) . The currently selected conversation can be exported by passing * for the name.
      Parameters:
      name - the name argument (not null)
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getFunctionCalls

      public boolean getFunctionCalls​(JsonObject json)
      This method returns the function calls in json if the output contains any. Returns true if one or more function calls were returned, otherwise returns false. This only applies to manual function tool calling, not automatic JS tool calls.
      Parameters:
      json - the json argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • getLastJsonData

      public void getLastJsonData​(JsonObject json)
      Provides details about the last method called on this object instance. While many methods do not generate information, some allow you to retrieve details by accessing the last JSON data immediately after the method call returns.

      Methods that produce last JSON information include: getModels(StringTable) .

      Parameters:
      json - the json argument (not null)

    • getModels

      public void getModels​(StringTable st)
      Returns a list of models available to your account, such as GPT-4o and GPT-5. The models are listed in st, sorted in ascending, case-insensitive order. To access the raw JSON response after calling this method, use getLastJsonData(JsonObject) .
      Parameters:
      st - the st argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getOutputBd

      public void getOutputBd​(BinData bd)
      Returns in bd the binary output from the last call to ask(String), such as for an AI generated image.
      Parameters:
      bd - the bd argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getOutputJson

      public boolean getOutputJson​(JsonObject json)
      Returns the model's structured JSON output from the most recent ask(String), parsed into json. Use this after setting a schema with setOutputSchema(String, JsonObject, boolean) . Returns true and populates json when the output is valid JSON. Returns false if the model refused to produce the output (in which case getLastResponseRefused() is true and getRefusalText() contains the explanation), if there is no output, or if the output is not valid JSON. The raw JSON text is also available from getOutputText() .
      Parameters:
      json - the json argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • getOutputText

      public String getOutputText()
      Returns the text output from the last call to ask(String).
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getOutputTextSb

      public void getOutputTextSb​(StringBuilder sb)
      Returns the text output, appended to sb, from the last call to ask(String).
      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getSearchResults

      public boolean getSearchResults​(JsonObject json)
      Returns the web search sources the model used in the most recent ask(String), if web search was enabled via the web_search param of setAskParams(JsonObject) . Returns true if the last ask(String) performed one or more web searches, in which case the normalized results are placed in json. Returns false if no web search occurred.

      Chilkat normalizes the differing citation formats of each AI provider into a single flat structure. json is populated as follows: 

      {
   "search_results": [
     {
       "url": "https://example.com/article",
       "title": "Example Article Title",
       "snippet": "The relevant excerpt the model drew from...",
       "page_age": "2025-08-01"
     }
   ]
 }

      The snippet and page_age members are populated only when the provider supplies them, and may be absent otherwise. Each provider returns a different citation shape (for example, OpenAI returns url_citation annotations with character offsets, Anthropic returns web_search_tool_result content blocks, Google returns groundingMetadata, and Perplexity returns a search_results array). The full, unmodified provider response — including any character-offset annotations not represented in the normalized form — remains available via getLastJsonData(JsonObject) .

      Streaming: In streaming mode, a standardized web_search_call event is delivered through nextAiEvent(int, StringBuilder, StringBuilder) when the provider begins a search, and the normalized results are available from this method after the null_terminator event completes the response.

      Parameters:
      json - the json argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • importConvo

      public void importConvo​(String name, JsonObject json)
      Imports the conversation from json and assigns it the name in name.
      Parameters:
      name - the name argument (not null)
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddFileData

      public void inputAddFileData​(String filename, BinData bd, String summary)
      Adds file data, such as a PDF, to the potentially multimodal input that will be sent in the next call to ask(String). The bd contains the file data.

      If getFullTranscript() is _CKFALSE_, summary is sent in subsequent interactions instead of the file data. If getFullTranscript() is true, summary is not sent, and the file data is re-sent in each interaction.

      This method cannot be used with DeepSeek.

      Parameters:
      filename - the filename argument (not null)
      bd - the bd argument (not null)
      summary - the summary argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddFileId

      public void inputAddFileId​(String file_id, String mime_type)
      Adds a reference to a previously uploaded file. The file_id is the id returned from the provider when originally uploading the file. The mime_type, such as "application/pdf", "application/json", "text/xml", etc. is needed for some AI providers such as Google.
      Parameters:
      file_id - the file_id argument (not null)
      mime_type - the mime_type argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddFileUrl

      public void inputAddFileUrl​(String url, String summary)
      Adds a file located at a url to the potentially multimodal input that will be sent in the next call to ask(String).

      If getFullTranscript() is _CKFALSE_, summary is sent in subsequent interactions instead of the file URL. If getFullTranscript() is true, summary is not sent, and the file URL is re-sent in each interaction.

      This method cannot be used with DeepSeek.

      Parameters:
      url - the url argument (not null)
      summary - the summary argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddFnResult

      public void inputAddFnResult​(String call_id, String fnResult)
      Provide a function call result to the model. This only applies to manual function tool calling, not automatic JS tool calls.
      Parameters:
      call_id - the call_id argument (not null)
      fnResult - the fnResult argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddImageData

      public void inputAddImageData​(BinData bd, String summary)
      Adds an image to the potentially multimodal input that will be sent in the next call to ask(String). The bd contains the images data. The image data must be jpeg, png, or webp format.

      If getFullTranscript() is _CKFALSE_, summary is sent in subsequent interactions instead of the image data. If getFullTranscript() is true, summary is not sent, and the image data is re-sent in each interaction.

      This method cannot be used with DeepSeek. DeepSeek does not appear to expose an OpenAI-compatible vision model (yet). You cannot send image URLs or image data to DeepSeek.

      Parameters:
      bd - the bd argument (not null)
      summary - the summary argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddImageFileId

      public void inputAddImageFileId​(String file_id, String mime_type)
      Adds a reference to a previously uploaded image file. The file_id is the id returned from the provider when originally uploading the file. The mime_type, such as "image/jpeg" is needed for some AI providers such as Google.

      Note: At this time, only OpenAI and Google support the ability to upload once → get file_id → reuse in later requests' workflow for images.

      Parameters:
      file_id - the file_id argument (not null)
      mime_type - the mime_type argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddImageUrl

      public void inputAddImageUrl​(String url, String summary)
      Adds an image located at a url to the potentially multimodal input that will be sent in the next call to ask(String).

      If getFullTranscript() is _CKFALSE_, summary is sent in subsequent interactions instead of the image URL. If getFullTranscript() is true, summary is not sent, and the image URL is re-sent in each interaction.

      This method cannot be used with DeepSeek. DeepSeek does not appear to expose an OpenAI-compatible vision model (yet). You cannot send image URLs or image data to DeepSeek.

      Parameters:
      url - the url argument (not null)
      summary - the summary argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddText

      public void inputAddText​(String text)
      Adds text to the potentially multimodal input that will be sent in the next call to ask(String).
      Parameters:
      text - the text argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputAddTextSb

      public void inputAddTextSb​(StringBuilder sb)
      Adds text to the potentially multimodal input that will be sent in the next call to ask(String).
      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • inputClear

      public void inputClear()
      Clears the inputs to be sent in the next call to ask(String).

    • listConvos

      public void listConvos​(StringTable st)
      Returns the full list of conversation names in st.
      Parameters:
      st - the st argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • newConvo

      public void newConvo​(String name, String sysMsg, String devMsg)
      Creates and initializes a transcript for a new conversation. The name is a unique name for the conversation. You can reference the conversation by this name, such as for the exportConvo(String, JsonObject) method.

      The sysMsg sets the broad behavior, tone, and role of the assistant.

      Example: "You are a polite tutor who explains concepts clearly and simply."

      Think of it as the high-level persona or instructions the model follows throughout the conversation. The devMsg provides more technical or policy-level guidance.

      Example: "Always respond in Markdown. Do not reveal internal reasoning. Keep answers under 200 words."

      It’s like hidden scaffolding to enforce app rules, formatting, or safety constraints.

      Note: The first conversation created is automatically set as the getSelectedConvo() . You can use any unique name for a conversation except *.

      Parameters:
      name - the name argument (not null)
      sysMsg - the sysMsg argument (not null)
      devMsg - the devMsg argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • nextAiEvent

      public void nextAiEvent​(int maxWaitMs, StringBuilder sbName, StringBuilder sbDelta)
      Retrieves the next available AI streaming mode response update. Use the pollAi(boolean) method to check if a response update is immediately accessible. The event name is returned in sbName. If the event name is delta, the text is returned in sbDelta.

      For the complete raw event JSON, use the getLastJsonData(JsonObject) function. Note that the raw JSON format varies by AI provider.

      Each AI provider (e.g., OpenAI, Claude, xAI) sends a unique set of events. Some of these events mark the start and end of sections and content parts, while others do not. Chilkat standardizes these events and returns the following event types.

      • response_created — The server acknowledges the request and has created a response object.

        Nothing has been streamed yet — it’s just the signal that the response pipeline is open.

      • empty — Some AI providers send empty heartbeat / keep-alive updates to ensure the stream stays open and proxies don't time out.
      • output_item_added — A new output item has been added to the response. An “output item” is a top-level container — could be text, tool call, or other structured content.
      • content_part_added — Within the output item, the model starts a new content part.

        A content part is typically a segment of a specific type (e.g., text, JSON snippet, or image reference).

      • delta — These are the incremental text tokens being streamed.

        Each delta contains the next piece of text (like characters or words).

        You’ll see many of these in sequence while the model is generating.

      • output_text_done — Marks the end of the text streaming for that content part.

        No more deltas will arrive for this part.

      • content_part_done — Closes the current content part.

        Tells you the model is finished with that segment (e.g., done streaming a paragraph).

      • output_item_done — Closes the current output item entirely.

        Means that item is fully complete (all its parts are done).

      • response_completed — The entire response object is finished.

        No more items will be added, and the stream will soon close.

      • null_terminator — The stream is closed. All streaming responses end with a single null_terminator.
      • function_call — (starting in v11.4.0) The AI model is requesting a function call. This is for manual tool calling.
      • js_function_call — (starting in v11.4.0) The AI model is requesting a function call that Chilkat can execute automatically. Call streamingJsToolCall(StringBuilder) to run it. This covers both JavaScript tools (registerJsTools(StringBuilder, boolean, boolean)) and MCP tools (useMcp(Mcp, String)).
      • web_search_call — (starting in v11.6.0) The AI provider is performing a server-side web search while generating the response. This is an informational progress event (useful for showing a "Searching the web…" indicator); the application takes no action. The retrieved sources are available from getSearchResults(JsonObject) after the response completes.

      maxWaitMs defines the maximum wait time to receive the complete event. For instance, if pollAi(boolean) signals an available streaming update but only part of the event JSON has been received, the rest is probably on its way. In such cases, this method must wait to receive the entire JSON.

      Parameters:
      maxWaitMs - the maxWaitMs argument
      sbName - the sbName argument (not null)
      sbDelta - the sbDelta argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • pollAi

      public int pollAi​(boolean abort)
      Returns immediately with one of the following values:

      -1 - Error
      0 - No streaming event updates are available.
      1 - A streaming event updates is ready for retrieval via nextAiEvent(int, StringBuilder, StringBuilder)
      2 - The streaming AI response has already completed, or no streaming response is ongoing.

      If abort is true, then the streaming response is aborted and this method returns the value 2. Applications should pass in false for abort to continue streaming.

      Parameters:
      abort - the abort argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • registerJsTools

      public void registerJsTools​(StringBuilder sb, boolean evalOnly, boolean allowAllKeyword)
      Adds JavaScript tool functions to the AI. This function can be called multiple times to add tool functions from multiple JavaScript sources. The JavaScript is passed in sb. If evalOnly is true, then the sb contains JavaScript to be run for the purpose of adding supporting functions and does not contain a toolRegistry.

      The allowAllKeyword indicates whether the all keyword is allowed in the toolPermissions. If multiple JavaScript tool sources are loaded with several calls to RegisterJsTools, we may not want one to clobber the permissions needed by another. The application can ensure this doesn't happen by setting this property to false.

      Parameters:
      sb - the sb argument (not null)
      evalOnly - the evalOnly argument
      allowAllKeyword - the allowAllKeyword argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • registerManualTools

      public void registerManualTools​(JsonObject json)
      Sets the tools JSON for AI requests.
      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setAskParams

      public void setAskParams​(JsonObject json)
      Sets additional ask(String) params such as:
      • effort (see below)
      • max_output_tokens (see below)
      • max_tool_iterations - v11.4.0 Applies only to automatic JavaScript tool function calls. Sets a maximum number of AI model tool responses that can be received. The default is 5. This is to prevent an unlikely and unexpected infinite cycle of AI model tool responses and automatic tool calling.
      • temperature (see below)
      • web_search - v11.6.0 A JSON object that enables provider-hosted web search (also called "grounding") so the model can retrieve live results and answer with citations. See below.
      • verbose_ai_logging- v11.4.0 Adds even more detailed logging to the ChilkatObject.getLastErrorText() , more than what is added when the ChilkatObject.getVerboseLogging() property is enabled.

      effort

      The effort can be set to none, minimal, low, medium, or high.

      Chilkat will automatically convert "effort" to the correct JSON member name and value based on the AI provider.

      API / Provider JSON Member for Effort

      OpenAI Responses API reasoning.effort → none|minimal|low|medium|high

      Anthropic Claude output_config.effort → low|medium|high

      Google Gemini generationConfig.thinkingConfig.thinkingLevel → LOW|HIGH

      OpenAI Chat Completions reasoning_effort → none|minimal|low|medium|high

      max_output_tokens

      Max output tokens simply limit how long the model’s response is allowed to be. It’s just a cap — the model may use fewer, but cannot exceed it.

      Chilkat will automatically convert "max_output_tokens" to the correct JSON member name based on the AI provider.

      API / Provider JSON Member for Max Tokens

      OpenAI Responses API max_output_tokens

      Anthropic Claude max_tokens

      Google Gemini generationConfig.maxOutputTokens

      OpenAI Chat Completions max_completion_tokens

      Typical limits (approximate)

      Different AI providers enforce different maximum output sizes:

      Provider / Model Typical Max Output Tokens

      OpenAI GPT-4, GPT-4 Turbo ~4,096–8,192 tokens

      OpenAI GPT-5 / GPT-5.1 Often ~8,192–16,384 tokens (varies by deployment)

      OpenAI o-series (o1, o1-mini, o3) ~4,096–8,192 tokens

      Anthropic Claude 3 / 3.5 ~4,096 tokens (fixed; cannot request more)

      Google Gemini 1.5 ~8,192–16,384 tokens

      xAI Grok 1.5 ~2,048–4,096 tokens

      Ollama / local models Usually 1,024–4,096 depending on model size

      temperature

      Most modern AI APIs (including OpenAI’s) allow a temperature range from 0.0 to 2.0. Chilkat will ignore and not send a temperature having a value outside this range.

      Here’s the breakdown:

      • 0.0 → 1.0: Traditional range used by older models and most examples.
      • >1.0 up to 2.0: Expands randomness even further. Outputs can become highly creative, unusual, or less controlled.

      Practical guidance:

      Temperature Behavior

      0.0 Fully deterministic. Same prompt → same answer.

      0.1–0.5 Focused, safe, factual, ideal for coding and instructions.

      0.6–1.0 Creative but still coherent. Great for writing or brainstorming.

      1.1–2.0 Very creative, exploratory, sometimes chaotic; useful for idea generation or stylistic experimentation.

      The valid range is technically 0.0 to 2.0, but the commonly useful range is usually 0.0 to ~1.2 for most applications.

      web_search (starting in v11.6.0)

      The web_search param is a JSON object that turns on the AI provider's server-side web search tool. The provider performs the search while generating the response, and the model answers using the retrieved results. After the ask(String), the retrieved sources can be obtained by calling getSearchResults(JsonObject) .

      Example: 

      {
   "web_search": {
     "enabled": true,
     "max_uses": 3,
     "allowed_domains": [ "wikipedia.org", "nasa.gov" ],
     "blocked_domains": [ ],
     "recency": "week",
     "user_location": {
       "country": "US",
       "city": "Chicago",
       "region": "Illinois",
       "timezone": "America/Chicago"
     }
   }
 }

      Chilkat maps each field to the equivalent option for the selected getProvider() and silently ignores fields the provider does not support. Only enabled is required; every other field is optional.

      • enabled — If true, web search is offered to the model for this ask(String). For perplexity, search is always on, so this is a no-op.
      • max_uses — The maximum number of searches the model may perform while answering. This is the primary cost-control knob (see the billing note below).
      • allowed_domains — An array of domains. When present, search results are restricted to these domains.
      • blocked_domains — An array of domains to exclude from results. Do not specify both allowed_domains and blocked_domains in the same request unless the provider permits it.
      • recency — Limits results by age. Possible values are day, week, month, or year.
      • user_location — An optional object with country, city, region, and timezone members used to localize results.

      Provider support matrix

      Field openai claude google xai perplexity

      enabled web_search tool web_search tool google_search web_search tool always on

      max_uses — ✓ — — —

      allowed_domains ✓ ✓ — ✓ ✓

      blocked_domains — ✓ — ✓ ✓

      recency — — — — ✓

      user_location ✓ ✓ — — —

      xAI (Grok): Web search uses xAI's Agent Tools API on the Responses endpoint. Chilkat automatically routes a Grok web search request to that endpoint, so a web-search-capable Grok model (for example grok-4.5) is required. For Grok, only allowed_domains and blocked_domains (each limited to 5 domains, and mutually exclusive) are supported. xAI's older chat-completions "Live Search" is deprecated.

      Not supported: deepseek and mistral (chat) do not expose a web search tool. If web_search is set for these providers, the ask(String) proceeds without search and a note is written to the ChilkatObject.getLastErrorText() . This keeps provider-switching code working when only the getProvider() property changes.

      Billing note: Most providers bill web searches separately from tokens (typically per 1,000 searches). Use max_uses where supported to bound per-request cost.

      Streaming: When getStreaming() is enabled, a web_search_call event is delivered through nextAiEvent(int, StringBuilder, StringBuilder) while the provider performs a search.

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setConnectionSettings

      public void setConnectionSettings​(Socket sock)
      This method copies connection settings, including HTTP proxy, SOCKS proxy, network interface IP address, and other related settings from sock. It's optional; if not used, default settings apply. Call this method before sending REST API requests to an AI provider.
      Parameters:
      sock - the sock argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setOutputSchema

      public void setOutputSchema​(String name, JsonObject schema, boolean strict)
      Requests schema-constrained JSON output (structured output) for subsequent calls to ask(String). name is a short schema name (letters, digits, underscores, and hyphens) used as an identifier by some providers. schema is the desired output shape as a JSON Schema. strict (strict) requests strict conformance where the provider supports it.

      Pass an empty string for name to clear a previously-set schema, which disables structured output.

      When strict (strict) is true, Chilkat automatically augments the schema for the providers that require it — adding "additionalProperties": false and marking every property required on each object — so an ordinary JSON Schema can be supplied. For example, schema might be: 

      {
   "type": "object",
   "properties": {
     "name": { "type": "string" },
     "age": { "type": "integer" }
   },
   "required": ["name", "age"]
 }

      After ask(String), the model's JSON is available as text from getOutputText() or parsed from getOutputJson(JsonObject) .

      Provider support: OpenAI, Anthropic Claude, Google Gemini, xAI Grok, Mistral, and Perplexity return schema-conforming JSON. DeepSeek supports JSON-object mode only (a valid JSON object is returned, but the schema is not enforced).

      Parameters:
      name - the name argument (not null)
      schema - the schema argument (not null)
      strict - the strict argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProviderParams

      public void setProviderParams​(JsonObject json)
      Sets additional provider params needed for some pre-defined providers. As of this current version, the possible params are:
      1. azure.clientId, a GUID/UUID such as 17280f2d-f709-4a7b-af1d-9928190e13cf
      2. azure.clientSecret, such as UZc8Q~YBrRIgfe_zbAOwWV.8ikuHa3JJF7LvCdt.
      3. azure.tenantId, a GUID/UUID such as aa4b5625-a31f-44dd-94ec-e2f6c0c64d2c
      4. azure.location, such as eastus
      5. azure.subscription, a GUID/UUID such as 4abd4bf6-5260-4795-90f6-1e91ce4f582c

      Parameters:
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sleepMs

      public void sleepMs​(int millisec)
      This method is provided for convenience. It causes the calling thread to sleep for a number of milliseconds.
      Parameters:
      millisec - the millisec argument

    • streamingJsToolCall

      public void streamingJsToolCall​(StringBuilder sb)
      Handles a js_function_call event within a streaming ask(String) response loop by automatically executing the requested tool and adding its result to the conversation. The tool may be a JavaScript tool (registered with registerJsTools(StringBuilder, boolean, boolean)) or an MCP tool (registered with useMcp(Mcp, String)).
      Parameters:
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadFile

      public String uploadFile​(String path, String mimeType)
      Uploads a file and returns the file_id (or uri) that can be used to reference the pre-uploaded file using InputAddFileId before an Ask. Files can be uploaded to the following providers: openai, gemini, claude, and grok. The mimeType specifies the MIME type, such as "application/pdf" or "text/plain". If mimeType is the emptys string, Chilkat will automatically choose the MIME type based on the filename extension.
      Parameters:
      path - the path argument (not null)
      mimeType - the mimeType argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadFileBd

      public String uploadFileBd​(BinData bd, String filename, String mimeType)
      Uploads the contents of bd and returns the file_id (or uri) that can be used to reference the pre-uploaded file using InputAddFileId before an Ask. Files can be uploaded to the following providers: openai, gemini, claude, and grok. The filename is mostly informational. The mimeType specifies the MIME type, such as "application/pdf" or "text/plain". If mimeType is the emptys string, Chilkat will automatically choose the MIME type based on the extension of the filename passed in filename.
      Parameters:
      bd - the bd argument (not null)
      filename - the filename argument (not null)
      mimeType - the mimeType argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uploadFileSb

      public String uploadFileSb​(StringBuilder sb, String filename, String mimeType)
      Uploads the contents of sb and returns the file_id (or uri) that can be used to reference the pre-uploaded file using InputAddFileId before an Ask. Files can be uploaded to the following providers: openai, gemini, claude, and grok. The filename is mostly informational. The mimeType specifies the MIME type, such as "application/pdf" or "text/plain". If mimeType is the emptys string, Chilkat will automatically choose the MIME type based on the extension of the filename passed in filename. It is the utf-8 byte representation of the string that is uploaded.
      Parameters:
      sb - the sb argument (not null)
      filename - the filename argument (not null)
      mimeType - the mimeType argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useMcp

      public void useMcp​(Mcp cMcp, String namePrefix)
      Registers the tools provided by the connected MCP (Model Context Protocol) server cMcp so the AI model can call them during a conversation. This lists the server's tools (a network operation) and namespaces each tool name using the prefix in namePrefix (to avoid collisions between servers and with JavaScript tools).

      When the model requests one of these tools, Chilkat automatically routes the call to the MCP server via Mcp.CallTool, adds the result to the conversation, and continues the ask(String). An informational ProgressInfo event named McpToolCall (value = the qualified tool name) is emitted for each automatic call. MCP tools may be mixed with JavaScript tools (registerJsTools(StringBuilder, boolean, boolean)) in the same conversation.

      The cMcp Mcp object must already be connected (see Mcp.Connect) and must remain valid for as long as its tools are in use. Tool use requires a conversation; it cannot be used with a stateless query.

      Parameters:
      cMcp - the cMcp argument (not null)
      namePrefix - the namePrefix argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener