@chilkat/react-native 11.6.1

package/src/specs/Ai.nitro.ts

@@ -0,0 +1,1288 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { BinData } from './BinData.nitro'
+import type { JsonObject } from './JsonObject.nitro'
+import type { Mcp } from './Mcp.nitro'
+import type { Socket } from './Socket.nitro'
+import type { StringBuilder } from './StringBuilder.nitro'
+import type { StringTable } from './StringTable.nitro'
+
+/**
+ * Use one consistent API for multiple AI providers.
+ *
+ * `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:**
+ * `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](https://www.chilkatsoft.com/markdown_to_html_overview.asp).
+ * For an extended overview, see
+ * [Ai Class Overview](https://www.chilkatsoft.com/ai_class_overview.asp).
+ *
+ * Each `Ai` instance owns a native Chilkat object. It is released when the JavaScript object is
+ * garbage collected, or immediately by `dispose()`; any use after `dispose()` throws.
+ * Create one with `new Ai()`.
+ *
+ * Methods that can take a while (network, files, compression, key generation) also have an
+ * `...Async` form returning a `Promise`; it runs on a native worker thread so the UI keeps
+ * rendering. While such a call is pending, every other call on this object throws, except
+ * {@link Ai.abort} and assigning {@link Ai.onPercentDone} / {@link Ai.onProgressInfo}.
+ */
+export interface Ai extends HybridObject<{ ios: 'c++', android: 'c++' }> {
+  // ---- Properties ----
+
+  /**
+   * Provides HTML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorHtml: string
+
+  /**
+   * Provides plain text information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorText: string
+
+  /**
+   * Provides XML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorXml: string
+
+  /**
+   * Version of the component/library, such as "10.1.0"
+   *
+   * This property is read-only.
+   */
+  readonly version: string
+
+  /**
+   * If set to a file path, this property logs the LastErrorText of each Chilkat method or property
+   * call to the specified file. This logging helps identify the context and history of Chilkat
+   * calls leading up to any crash or hang, aiding in debugging.
+   *
+   * Enabling the VerboseLogging property provides more detailed information.
+   *
+   * This property is mainly used for debugging rare instances where a Chilkat method call causes a
+   * hang or crash, which should generally not happen.
+   *
+   * Possible causes of hangs include:
+   *
+   * - A timeout property set to 0, indicating an infinite timeout.
+   *
+   * - A hang occurring within an event callback in the application code.
+   *
+   * - An internal bug in the Chilkat code causing the hang.
+   */
+  debugLogFilePath: string
+
+  /**
+   * If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may
+   * contain more verbose information. The default value is `false`. Verbose logging should only be
+   * used for debugging. The potentially large quantity of logged information may adversely affect
+   * peformance.
+   */
+  verboseLogging: boolean
+
+  /**
+   * Indicates the success or failure of the most recent method call: `true` means success, `false`
+   * means failure. This property remains unchanged by property setters or getters. This method is
+   * present to address challenges in checking for null or Nothing returns in certain programming
+   * languages. Note: This property does not apply to methods that return integer values or to
+   * boolean-returning methods where the boolean does not indicate success or failure.
+   */
+  lastMethodSuccess: boolean
+
+  /**
+   * 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 {@link Ai.baseUrl}
+   * and {@link Ai.apiSpec} 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 {@link
+   * Ai.apiSpec} to `ChatCompletions`, so you only need to set {@link Ai.baseUrl} (plus {@link
+   * Ai.apiKey} and {@link Ai.model}). 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`.
+   */
+  provider: string
+
+  /**
+   * 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.
+   */
+  selectedConvo: string
+
+  /**
+   * This is the API key used for authentication. Use your API key that matches your {@link
+   * Ai.provider}.
+   *
+   * **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
+   */
+  apiKey: string
+
+  /**
+   * 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 {@link Ai.getModels}.
+   *
+   * The default value is the empty string. A model must always be specified. Chilkat won't try to
+   * guess or default to a model.
+   */
+  model: string
+
+  /**
+   * 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.
+   */
+  fullTranscript: boolean
+
+  /**
+   * When set to `true`, the {@link Ai.ask} 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`.
+   */
+  streaming: boolean
+
+  /**
+   * 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.**
+   */
+  heartbeatMs: number
+
+  /**
+   * 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`.
+   */
+  hostedConvo: boolean
+
+  /**
+   * This is a catch-all property to be used for uncommon needs. This property defaults to the empty
+   * string, and should typically remain empty.
+   */
+  uncommonOptions: string
+
+  /**
+   * 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.
+   */
+  idleTimeoutMs: number
+
+  /**
+   * The HTTP response status code for the last {@link Ai.ask} 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.
+   *
+   * This property is read-only.
+   */
+  readonly responseStatusCode: number
+
+  /**
+   * 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 {@link Ai.provider} property is `openai`. Setting the {@link Ai.provider} property to a
+   * value other than `custom` will also automatically set this property to the correct and needed
+   * value.
+   */
+  apiSpec: string
+
+  /**
+   * 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 {@link Ai.provider} property is `openai`. Setting the {@link Ai.provider}
+   * property to a value other than `custom` will also automatically set this property to the
+   * correct and needed value.
+   */
+  baseUrl: string
+
+  /**
+   * For custom {@link Ai.provider}'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.
+   */
+  apiKeyHeader: string
+
+  /**
+   * `true` if the response output has function calls. Otherwise `false`. This only applies to
+   * manual function tool calling, not automatic JS tool calls.
+   *
+   * This property is read-only.
+   */
+  readonly hasFunctionCalls: boolean
+
+  /**
+   * 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.
+   */
+  jsToolTimeout: number
+
+  /**
+   * 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`.
+   */
+  enableSecrets: boolean
+
+  /**
+   * Read-only. `true` if the model refused to produce the requested structured output during the
+   * most recent {@link Ai.ask}. When a refusal occurs, {@link Ai.getOutputJson} returns `false` and
+   * the provider's explanation is available in {@link Ai.refusalText}. This property is reset at
+   * the start of each {@link Ai.ask}.
+   *
+   * This property is read-only.
+   */
+  readonly lastResponseRefused: boolean
+
+  /**
+   * Read-only. When {@link Ai.lastResponseRefused} is `true`, this is the model's message
+   * explaining why it declined to produce the requested structured output. Otherwise it is the
+   * empty string.
+   *
+   * This property is read-only.
+   */
+  readonly refusalText: string
+
+  // ---- Methods ----
+
+  /**
+   * 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 {@link
+   * Ai.exportConvo} 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 {@link Ai.selectedConvo}.
+   * You can use any unique name for a conversation except `*`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  newConvo(name: string, sysMsg: string, devMsg: string): void
+
+  /**
+   * Exports the conversation specified by `name` to `json`, replacing `json`'s contents with the
+   * exported transcript. You can later import a conversation using {@link Ai.importConvo}. The
+   * currently selected conversation can be exported by passing `*` for the `name`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  exportConvo(name: string, json: JsonObject): void
+
+  /**
+   * Imports the conversation from `json` and assigns it the name in `name`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  importConvo(name: string, json: JsonObject): void
+
+  /**
+   * Returns the full list of conversation names in `st`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  listConvos(st: StringTable): void
+
+  /**
+   * Deletes the conversation by its `name`. If `name` equals `*` then all conversations are
+   * deleted.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  deleteConvo(name: string): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  setConnectionSettings(sock: Socket): void
+
+  /**
+   * 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.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Ai.askAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  ask(outputType: string): void
+
+  /**
+   * Asynchronous form of {@link Ai.ask}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Ai.abort} (which cancels it) and the {@link Ai.onPercentDone} /
+   * {@link Ai.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  askAsync(outputType: string): Promise<void>
+
+  /**
+   * 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: {@link Ai.getModels}.
+   */
+  getLastJsonData(json: JsonObject): void
+
+  /**
+   * 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 {@link Ai.getLastJsonData}.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Ai.getModelsAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  getModels(st: StringTable): void
+
+  /**
+   * Asynchronous form of {@link Ai.getModels}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Ai.abort} (which cancels it) and the {@link Ai.onPercentDone} /
+   * {@link Ai.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  getModelsAsync(st: StringTable): Promise<void>
+
+  /**
+   * Adds text to the potentially multimodal input that will be sent in the next call to {@link
+   * Ai.ask}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddText(text: string): void
+
+  /**
+   * Returns the text output from the last call to {@link Ai.ask}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  getOutputText(): string
+
+  /**
+   * Returns the text output, appended to `sb`, from the last call to {@link Ai.ask}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  getOutputTextSb(sb: StringBuilder): void
+
+  /**
+   * Clears the inputs to be sent in the next call to {@link Ai.ask}.
+   */
+  inputClear(): void
+
+  /**
+   * Adds text to the potentially multimodal input that will be sent in the next call to {@link
+   * Ai.ask}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddTextSb(sb: StringBuilder): void
+
+  /**
+   * Adds an image to the potentially multimodal input that will be sent in the next call to {@link
+   * Ai.ask}. The `bd` contains the images data. The image data must be jpeg, png, or webp format.
+   *
+   * If {@link Ai.fullTranscript} is _CKFALSE_, `summary` is sent in subsequent interactions instead
+   * of the image data. If {@link Ai.fullTranscript} 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddImageData(bd: BinData, summary: string): void
+
+  /**
+   * Adds an image located at a `url` to the potentially multimodal input that will be sent in the
+   * next call to {@link Ai.ask}.
+   *
+   * If {@link Ai.fullTranscript} is _CKFALSE_, `summary` is sent in subsequent interactions instead
+   * of the image URL. If {@link Ai.fullTranscript} 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddImageUrl(url: string, summary: string): void
+
+  /**
+   * Adds file data, such as a PDF, to the potentially multimodal input that will be sent in the
+   * next call to {@link Ai.ask}. The `bd` contains the file data.
+   *
+   * If {@link Ai.fullTranscript} is _CKFALSE_, `summary` is sent in subsequent interactions instead
+   * of the file data. If {@link Ai.fullTranscript} is `true`, `summary` is not sent, and the file
+   * data is re-sent in each interaction.
+   *
+   * This method cannot be used with `DeepSeek`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddFileData(filename: string, bd: BinData, summary: string): void
+
+  /**
+   * Adds a file located at a `url` to the potentially multimodal input that will be sent in the
+   * next call to {@link Ai.ask}.
+   *
+   * If {@link Ai.fullTranscript} is _CKFALSE_, `summary` is sent in subsequent interactions instead
+   * of the file URL. If {@link Ai.fullTranscript} is `true`, `summary` is not sent, and the file
+   * URL is re-sent in each interaction.
+   *
+   * This method cannot be used with `DeepSeek`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddFileUrl(url: string, summary: string): void
+
+  /**
+   * 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 {@link Ai.nextAiEvent}
+   *
+   * `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.
+   */
+  pollAi(abort: boolean): number
+
+  /**
+   * Retrieves the next available AI streaming mode response update. Use the {@link Ai.pollAi}
+   * 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 {@link Ai.getLastJsonData} 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 {@link Ai.streamingJsToolCall} to run it. This
+   *   covers both **JavaScript** tools ({@link Ai.registerJsTools}) and **MCP** tools ({@link
+   *   Ai.useMcp}).
+   *
+   * - `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 {@link Ai.getSearchResults} after the response completes.
+   *
+   * `maxWaitMs` defines the maximum wait time to receive the complete event. For instance, if
+   * {@link Ai.pollAi} 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  nextAiEvent(maxWaitMs: number, sbName: StringBuilder, sbDelta: StringBuilder): void
+
+  /**
+   * This method is provided for convenience. It causes the calling thread to sleep for a number of
+   * milliseconds.
+   */
+  sleepMs(millisec: number): void
+
+  /**
+   * Sets additional provider params needed for some pre-defined providers. As of this current
+   * version, the possible params are:
+   *
+   * - `azure.clientId`, a GUID/UUID such as 17280f2d-f709-4a7b-af1d-9928190e13cf
+   *
+   * - `azure.clientSecret`, such as UZc8Q~YBrRIgfe_zbAOwWV.8ikuHa3JJF7LvCdt.
+   *
+   * - `azure.tenantId`, a GUID/UUID such as aa4b5625-a31f-44dd-94ec-e2f6c0c64d2c
+   *
+   * - `azure.location`, such as `eastus`
+   *
+   * - `azure.subscription`, a GUID/UUID such as 4abd4bf6-5260-4795-90f6-1e91ce4f582c
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  setProviderParams(json: JsonObject): void
+
+  /**
+   * Sets additional {@link Ai.ask} 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 {@link
+   * Ai.lastErrorText}, more than what is added when the {@link Ai.verboseLogging} 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 {@link Ai.ask}, the retrieved sources can be
+   * obtained by calling {@link Ai.getSearchResults}.
+   *
+   * 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 {@link Ai.provider} 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 {@link Ai.ask}. 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 {@link Ai.ask} proceeds without search and a note
+   * is written to the {@link Ai.lastErrorText}. This keeps provider-switching code working when
+   * only the {@link Ai.provider} 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 {@link Ai.streaming} is enabled, a `web_search_call` event is delivered
+   * through {@link Ai.nextAiEvent} while the provider performs a search.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  setAskParams(json: JsonObject): void
+
+  /**
+   * Sets the tools JSON for AI requests.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  registerManualTools(json: JsonObject): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  getFunctionCalls(json: JsonObject): void
+
+  /**
+   * Returns the web search sources the model used in the most recent {@link Ai.ask}, if web search
+   * was enabled via the `web_search` param of {@link Ai.setAskParams}. Returns `true` if the last
+   * {@link Ai.ask} 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
+   * {@link Ai.getLastJsonData}.
+   *
+   * **Streaming:** In streaming mode, a standardized `web_search_call` event is delivered through
+   * {@link Ai.nextAiEvent} when the provider begins a search, and the normalized results are
+   * available from this method after the `null_terminator` event completes the response.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  getSearchResults(json: JsonObject): void
+
+  /**
+   * 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 {@link
+   * Ai.ask}. 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 ({@link
+   * Ai.registerJsTools}) 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.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Ai.useMcpAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  useMcp(cMcp: Mcp, namePrefix: string): void
+
+  /**
+   * Asynchronous form of {@link Ai.useMcp}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Ai.abort} (which cancels it) and the {@link Ai.onPercentDone} /
+   * {@link Ai.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  useMcpAsync(cMcp: Mcp, namePrefix: string): Promise<void>
+
+  /**
+   * Requests schema-constrained JSON output (structured output) for subsequent calls to {@link
+   * Ai.ask}. `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 {@link Ai.ask}, the model's JSON is available as text from {@link Ai.getOutputText} or
+   * parsed from {@link Ai.getOutputJson}.
+   *
+   * **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).
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  setOutputSchema(name: string, schema: JsonObject, strict: boolean): void
+
+  /**
+   * Returns the model's structured JSON output from the most recent {@link Ai.ask}, parsed into
+   * `json`. Use this after setting a schema with {@link Ai.setOutputSchema}. Returns `true` and
+   * populates `json` when the output is valid JSON. Returns `false` if the model refused to produce
+   * the output (in which case {@link Ai.lastResponseRefused} is `true` and {@link Ai.refusalText}
+   * contains the explanation), if there is no output, or if the output is not valid JSON. The raw
+   * JSON text is also available from {@link Ai.getOutputText}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  getOutputJson(json: JsonObject): void
+
+  /**
+   * Provide a function call result to the model. This only applies to `manual function tool
+   * calling`, not automatic JS tool calls.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddFnResult(callId: string, fnResult: string): void
+
+  /**
+   * 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`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  registerJsTools(sb: StringBuilder, evalOnly: boolean, allowAllKeyword: boolean): void
+
+  /**
+   * Handles a `js_function_call` event within a streaming {@link Ai.ask} response loop by
+   * automatically executing the requested tool and adding its result to the conversation. The tool
+   * may be a JavaScript tool (registered with {@link Ai.registerJsTools}) or an MCP tool
+   * (registered with {@link Ai.useMcp}).
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Ai.streamingJsToolCallAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  streamingJsToolCall(sb: StringBuilder): void
+
+  /**
+   * Asynchronous form of {@link Ai.streamingJsToolCall}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Ai.abort} (which cancels it) and the {@link Ai.onPercentDone} /
+   * {@link Ai.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  streamingJsToolCallAsync(sb: StringBuilder): Promise<void>
+
+  /**
+   * Adds a reference to a previously uploaded file. The `fileId` is the id returned from the
+   * provider when originally uploading the file. The `mimeType`, such as "application/pdf",
+   * "application/json", "text/xml", etc. is needed for some AI providers such as Google.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddFileId(fileId: string, mimeType: string): void
+
+  /**
+   * Returns in `bd` the binary output from the last call to {@link Ai.ask}, such as for an AI
+   * generated image.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  getOutputBd(bd: BinData): void
+
+  /**
+   * 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.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Ai.uploadFileAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  uploadFile(path: string, mimeType: string): string
+
+  /**
+   * Asynchronous form of {@link Ai.uploadFile}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Ai.abort} (which cancels it) and the {@link Ai.onPercentDone} /
+   * {@link Ai.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  uploadFileAsync(path: string, mimeType: string): Promise<string>
+
+  /**
+   * 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`.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Ai.uploadFileBdAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  uploadFileBd(bd: BinData, filename: string, mimeType: string): string
+
+  /**
+   * Asynchronous form of {@link Ai.uploadFileBd}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Ai.abort} (which cancels it) and the {@link Ai.onPercentDone} /
+   * {@link Ai.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  uploadFileBdAsync(bd: BinData, filename: string, mimeType: string): Promise<string>
+
+  /**
+   * 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.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link Ai.uploadFileSbAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  uploadFileSb(sb: StringBuilder, filename: string, mimeType: string): string
+
+  /**
+   * Asynchronous form of {@link Ai.uploadFileSb}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link Ai.abort} (which cancels it) and the {@link Ai.onPercentDone} /
+   * {@link Ai.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  uploadFileSbAsync(sb: StringBuilder, filename: string, mimeType: string): Promise<string>
+
+  /**
+   * Adds a reference to a previously uploaded image file. The `fileId` is the id returned from the
+   * provider when originally uploading the file. The `mimeType`, 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Ai.lastErrorText}.
+   */
+  inputAddImageFileId(fileId: string, mimeType: string): void
+
+  // ---- Events (ReactNativeGen_DESIGN.md §6) ----
+
+  /**
+   * Called with the percent completed (0..100) while a long-running method runs, when Chilkat
+   * can measure progress. Runs on the JavaScript thread, so it is only useful with the
+   * `...Async` methods (during a synchronous call the thread is busy and the events arrive
+   * after it returns). Assign `undefined` to remove.
+   */
+  onPercentDone?: (pctDone: number) => void
+
+  /**
+   * Called with a name/value pair of progress information while a long-running method runs
+   * (what is reported depends on the class and method). Runs on the JavaScript thread; see
+   * {@link Ai.onPercentDone}. Assign `undefined` to remove.
+   */
+  onProgressInfo?: (name: string, value: string) => void
+
+  /**
+   * Requests that the pending `...Async` call on this object stop at its next progress check.
+   * The promise then rejects with Chilkat's abort error. Chilkat checks at least every
+   * `heartbeatMs` milliseconds on the classes that have that property, so set it (e.g. 250)
+   * for a responsive cancel. Harmless when nothing is pending.
+   */
+  abort(): void
+}