Package com.smartgwt.client.ai

# Class AI

java.lang.Object
com.smartgwt.client.ai.AI

public class AI extends Object
Provides class methods for enabling and disabling the use of AI technology, registering and unregistering `AI engines`, and performing high-level operations using installed AI engines.

See Also:
  - `AI Mocking`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AI()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `addMockResponses(Map[] responses)`
  Alias for `addSpoofedResponses()`.
  `static void`
  `askDataQuestion(UserAIRequest question)`
  Asks AI to answer a question about the data of the application.
  `static void`
  `askDataQuestion(UserAIRequest question, DataSource... dataSources)`
  See `askDataQuestion()`
  `static void`
  `askDataQuestion(UserAIRequest question, DataSource[] dataSources, DataQuestionSettings settings)`
  See `askDataQuestion()`
  `static void`
  `askDataQuestion(UserAIRequest question, DataSource[] dataSources, DataQuestionSettings settings, AskDataQuestionResultCallback callback)`
  Asks AI to answer a question about the data of the application.
  `static void`
  `askDataQuestion(String question)`
  Asks AI to answer a question about the data of the application.
  `static void`
  `askDataQuestion(String question, DataSource... dataSources)`
  See `askDataQuestion()`
  `static void`
  `askDataQuestion(String question, DataSource[] dataSources, DataQuestionSettings settings)`
  See `askDataQuestion()`
  `static void`
  `askDataQuestion(String question, DataSource[] dataSources, DataQuestionSettings settings, AskDataQuestionResultCallback callback)`
  Asks AI to answer a question about the data of the application.
  `static void`
  `cancelDataQuestion(String questionId)`
  Cancels a data question if not already canceled.
  `static void`
  `checkModuleLoaded(String faultingAction)`
  `static void`
  `clearMockResponses()`
  Alias for `clearSpoofedResponses()`.
  `static Map[]`
  `getDataSourceSummaries()`
  Returns an array of summaries (see `getDataSourceSummary()`) for the specified DataSources, or all registered application DataSources if no list is provided.
  `static Map[]`
  `getDataSourceSummaries(String[] dataSourceNames)`
  See `getDataSourceSummaries()`
  `static Map[]`
  `getDataSourceSummaries(String[] dataSourceNames, Map settings)`
  Returns an array of summaries (see `getDataSourceSummary()`) for the specified DataSources, or all registered application DataSources if no list is provided.
  `static Map`
  `getDataSourceSummary(DataSource dataSource)`
  Returns a structured summary of a DataSource at a configurable detail level.
  `static Map`
  `getDataSourceSummary(DataSource dataSource, Map settings)`
  Returns a structured summary of a DataSource at a configurable detail level.
  `static Map`
  `getDataSourceSummary(String dataSource)`
  Returns a structured summary of a DataSource at a configurable detail level.
  `static Map`
  `getDataSourceSummary(String dataSource, Map settings)`
  Returns a structured summary of a DataSource at a configurable detail level.
  `static String`
  `getDefaultEngineId()`
  The ID of the default `AIEngine` to use.
  `static int`
  `getDefaultMaxRetries()`
  The defualt maximum number of retries for any one particular request to AI.
  `static Boolean`
  `getDisabled()`
  Whether AI is disabled.
  `static AIEngine`
  `getEngine()`
  Returns the `AIEngine` having the given engine ID.
  `static AIEngine`
  `getEngine(String engineId)`
  Returns the `AIEngine` having the given engine ID.
  `static String`
  `getMockingPolicy()`
  Returns the current `mockingPolicy`.
  `static boolean`
  `isEnabled()`
  Determines whether AI support is enabled.
  `static boolean`
  `moduleLoaded()`
  Reports whether the optional AI module is loaded for the page.
  `static void`
  `pauseDataQuestion(String questionId)`
  Pauses a data question if not already paused or canceled.
  `static boolean`
  `registerEngine(AIEngine engine)`
  Registers the given `AIEngine`.
  `static void`
  `resumeDataQuestion(String questionId)`
  Resumes a data question if paused.
  `static void`
  `sendPrompt(String dynamicString, Map context, AIResponseCallback callback)`
  Evaluates the given `dynamic string` to form a prompt string that is then sent as the request to the default AI engine.
  `static void`
  `setDefaultEngineId(String defaultEngineId)`
  The ID of the default `AIEngine` to use.
  `static void`
  `setDefaultMaxRetries(int defaultMaxRetries)`
  The defualt maximum number of retries for any one particular request to AI.
  `static void`
  `setDisabled(Boolean disabled)`
  Whether AI is disabled.
  `static void`
  `setMockingPolicy(String policy)`
  Sets `mockingPolicy`.
  `static boolean`
  `unregisterEngine(String engineId)`
  Unregisters an `AIEngine` specified by its ID.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### AI

    public AI()

- ## Method Details

  - ### setDefaultEngineId

    public static void setDefaultEngineId(String defaultEngineId)
    The ID of the default `AIEngine` to use.
    Parameters:
      `defaultEngineId` - new defaultEngineId. Default value is "gpt-4.1".

  - ### getDefaultEngineId

    public static String getDefaultEngineId()
    The ID of the default `AIEngine` to use.
    Returns:
      current value of defaultEngineId

  - ### setDefaultMaxRetries

    public static void setDefaultMaxRetries(int defaultMaxRetries)
    The defualt maximum number of retries for any one particular request to AI.
    Parameters:
      `defaultMaxRetries` - new defaultMaxRetries. Default value is 2.

  - ### getDefaultMaxRetries

    public static int getDefaultMaxRetries()
    The defualt maximum number of retries for any one particular request to AI.
    Returns:
      current value of defaultMaxRetries

  - ### setDisabled

    public static void setDisabled(Boolean disabled)
    Whether AI is disabled.

    By default, AI is disabled. This static property must be set to `false` and the `default` `AIEngine` must be registered in order to enable the use of AI in the application.

    Parameters:
      `disabled` - new disabled. Default value is true.

  - ### getDisabled

    public static Boolean getDisabled()
    Whether AI is disabled.

    By default, AI is disabled. This static property must be set to `false` and the `default` `AIEngine` must be registered in order to enable the use of AI in the application.

    Returns:
      current value of disabled

  - ### addMockResponses

    public static void addMockResponses(Map[] responses)
    Alias for `addSpoofedResponses()`.
    Parameters:
      `responses` - mock response entries

  - ### askDataQuestion

    public static void askDataQuestion(String question)
    Asks AI to answer a question about the data of the application.
    Parameters:
      `question` - The text of the end-user's question or their request for an answer to a data question.

  - ### askDataQuestion

    public static void askDataQuestion(UserAIRequest question)
    Asks AI to answer a question about the data of the application.
    Parameters:
      `question` - The text of the end-user's question or their request for an answer to a data question.

  - ### askDataQuestion

    public static void askDataQuestion(String question, DataSource... dataSources)
    See `askDataQuestion()`

  - ### askDataQuestion

    public static void askDataQuestion(UserAIRequest question, DataSource... dataSources)
    See `askDataQuestion()`

  - ### askDataQuestion

    public static void askDataQuestion(String question, DataSource[] dataSources, DataQuestionSettings settings)
    See `askDataQuestion()`

  - ### askDataQuestion

    public static void askDataQuestion(UserAIRequest question, DataSource[] dataSources, DataQuestionSettings settings)
    See `askDataQuestion()`

  - ### askDataQuestion

    public static void askDataQuestion(String question, DataSource[] dataSources, DataQuestionSettings settings, AskDataQuestionResultCallback callback)
    Asks AI to answer a question about the data of the application.
    Parameters:
      `question` - The text of the end-user's question or their request for an answer to a data question.
      `dataSources` - The available data sources. All data sources in the array must have a global ID. If `null`, then the array of all DataSources available to the AI module is used.
      `settings` - Settings to use when answering the data question.
      `callback` - The callback to call with the result.

  - ### askDataQuestion

    public static void askDataQuestion(UserAIRequest question, DataSource[] dataSources, DataQuestionSettings settings, AskDataQuestionResultCallback callback)
    Asks AI to answer a question about the data of the application.
    Parameters:
      `question` - The text of the end-user's question or their request for an answer to a data question.
      `dataSources` - The available data sources. All data sources in the array must have a global ID. If `null`, then the array of all DataSources available to the AI module is used.
      `settings` - Settings to use when answering the data question.
      `callback` - The callback to call with the result.

  - ### cancelDataQuestion

    public static void cancelDataQuestion(String questionId)
    Cancels a data question if not already canceled.
    Parameters:
      `questionId` - The ID of the data question to cancel.

  - ### clearMockResponses

    public static void clearMockResponses()
    Alias for `clearSpoofedResponses()`.

  - ### getDataSourceSummaries

    public static Map[] getDataSourceSummaries()
    Returns an array of summaries (see `getDataSourceSummary()`) for the specified DataSources, or all registered application DataSources if no list is provided. The `settings` parameter is passed through to each `getDataSourceSummary()` call.
    Returns:
      array of summary objects

  - ### getDataSourceSummaries

    public static Map[] getDataSourceSummaries(String[] dataSourceNames)
    See `getDataSourceSummaries()`

  - ### getDataSourceSummaries

    public static Map[] getDataSourceSummaries(String[] dataSourceNames, Map settings)
    Returns an array of summaries (see `getDataSourceSummary()`) for the specified DataSources, or all registered application DataSources if no list is provided. The `settings` parameter is passed through to each `getDataSourceSummary()` call.
    Parameters:
      `dataSourceNames` - DataSource IDs to summarize; defaults to `getDataSourceNames()`
      `settings` - passed through to `getDataSourceSummary()`
    Returns:
      array of summary objects

  - ### getDataSourceSummary

    public static Map getDataSourceSummary(DataSource dataSource)
    Returns a structured summary of a DataSource at a configurable detail level. In `"compact"` mode (default), only identity metadata, primary key, and foreign key relationships are included ? suitable for large-app DS selection where full field listings would exceed the AI context window. Higher detail levels progressively add field information via an `otherFields` property.

    Detail levels (set via `settings.detail`):

    - `"compact"` ? ID, title, description, fieldCount, pk, fk. No field list.
    - `"salientNames"` ? adds `otherFields` as an array of field name strings for salient/critical fields (PK and FK fields already shown in `pk`/`fk` are excluded).
    - `"salientTyped"` ? like salientNames but each entry is an object with `name`, `type`, and optionally `required` and `valueMap`.
    - `"allTyped"` ? like salientTyped but includes all fields, not just salient ones.
    - `"full"` ? all fields with the full `salientFieldAttributes` attribute mask.

    Settings:

    - `detail` (String) ? one of the levels above; default `"compact"`.
    - `maxFields` (Integer) ? cap on the number of fields in `otherFields`.
    - `excludeHousekeeping` (Boolean) ? omit auto-populated fields (creator, modifier, creatorTimestamp, modifierTimestamp); default `true` for all modes except `"full"`.
    - `includeData` (String) ? if set, includes representative data samples from available client-side caches. Values: `"fieldValues"` (per-field unique sample values added as `sampleValues` on each field entry) or `"records"` (whole sample records added as `sampleRecords`). Data is sourced from clientOnly cacheData, cacheAllData cacheResultSet, or any default-fetch (no operationId) ResultSet observing the DataSource ? no server requests are triggered.
    - `dataSampleCount` (Integer) ? maximum unique sample values per field (fieldValues mode) or sample records (records mode); default 3.
    - `dataSampleMaxSearch` (Integer) ? maximum cache records to scan when collecting unique sample values; default 100.
    Parameters:
      `dataSource` - DataSource or ID
    Returns:
      structured summary
    See Also:
      - `getDataSourceSummaries()`

  - ### getDataSourceSummary

    public static Map getDataSourceSummary(String dataSource)
    Returns a structured summary of a DataSource at a configurable detail level. In `"compact"` mode (default), only identity metadata, primary key, and foreign key relationships are included ? suitable for large-app DS selection where full field listings would exceed the AI context window. Higher detail levels progressively add field information via an `otherFields` property.

    Detail levels (set via `settings.detail`):

    - `"compact"` ? ID, title, description, fieldCount, pk, fk. No field list.
    - `"salientNames"` ? adds `otherFields` as an array of field name strings for salient/critical fields (PK and FK fields already shown in `pk`/`fk` are excluded).
    - `"salientTyped"` ? like salientNames but each entry is an object with `name`, `type`, and optionally `required` and `valueMap`.
    - `"allTyped"` ? like salientTyped but includes all fields, not just salient ones.
    - `"full"` ? all fields with the full `salientFieldAttributes` attribute mask.

    Settings:

    - `detail` (String) ? one of the levels above; default `"compact"`.
    - `maxFields` (Integer) ? cap on the number of fields in `otherFields`.
    - `excludeHousekeeping` (Boolean) ? omit auto-populated fields (creator, modifier, creatorTimestamp, modifierTimestamp); default `true` for all modes except `"full"`.
    - `includeData` (String) ? if set, includes representative data samples from available client-side caches. Values: `"fieldValues"` (per-field unique sample values added as `sampleValues` on each field entry) or `"records"` (whole sample records added as `sampleRecords`). Data is sourced from clientOnly cacheData, cacheAllData cacheResultSet, or any default-fetch (no operationId) ResultSet observing the DataSource ? no server requests are triggered.
    - `dataSampleCount` (Integer) ? maximum unique sample values per field (fieldValues mode) or sample records (records mode); default 3.
    - `dataSampleMaxSearch` (Integer) ? maximum cache records to scan when collecting unique sample values; default 100.
    Parameters:
      `dataSource` - DataSource or ID
    Returns:
      structured summary
    See Also:
      - `getDataSourceSummaries()`

  - ### getDataSourceSummary

    public static Map getDataSourceSummary(DataSource dataSource, Map settings)
    Returns a structured summary of a DataSource at a configurable detail level. In `"compact"` mode (default), only identity metadata, primary key, and foreign key relationships are included ? suitable for large-app DS selection where full field listings would exceed the AI context window. Higher detail levels progressively add field information via an `otherFields` property.

    Detail levels (set via `settings.detail`):

    - `"compact"` ? ID, title, description, fieldCount, pk, fk. No field list.
    - `"salientNames"` ? adds `otherFields` as an array of field name strings for salient/critical fields (PK and FK fields already shown in `pk`/`fk` are excluded).
    - `"salientTyped"` ? like salientNames but each entry is an object with `name`, `type`, and optionally `required` and `valueMap`.
    - `"allTyped"` ? like salientTyped but includes all fields, not just salient ones.
    - `"full"` ? all fields with the full `salientFieldAttributes` attribute mask.

    Settings:

    - `detail` (String) ? one of the levels above; default `"compact"`.
    - `maxFields` (Integer) ? cap on the number of fields in `otherFields`.
    - `excludeHousekeeping` (Boolean) ? omit auto-populated fields (creator, modifier, creatorTimestamp, modifierTimestamp); default `true` for all modes except `"full"`.
    - `includeData` (String) ? if set, includes representative data samples from available client-side caches. Values: `"fieldValues"` (per-field unique sample values added as `sampleValues` on each field entry) or `"records"` (whole sample records added as `sampleRecords`). Data is sourced from clientOnly cacheData, cacheAllData cacheResultSet, or any default-fetch (no operationId) ResultSet observing the DataSource ? no server requests are triggered.
    - `dataSampleCount` (Integer) ? maximum unique sample values per field (fieldValues mode) or sample records (records mode); default 3.
    - `dataSampleMaxSearch` (Integer) ? maximum cache records to scan when collecting unique sample values; default 100.
    Parameters:
      `dataSource` - DataSource or ID
      `settings` - detail level and field options
    Returns:
      structured summary
    See Also:
      - `getDataSourceSummaries()`

  - ### getDataSourceSummary

    public static Map getDataSourceSummary(String dataSource, Map settings)
    Returns a structured summary of a DataSource at a configurable detail level. In `"compact"` mode (default), only identity metadata, primary key, and foreign key relationships are included ? suitable for large-app DS selection where full field listings would exceed the AI context window. Higher detail levels progressively add field information via an `otherFields` property.

    Detail levels (set via `settings.detail`):

    - `"compact"` ? ID, title, description, fieldCount, pk, fk. No field list.
    - `"salientNames"` ? adds `otherFields` as an array of field name strings for salient/critical fields (PK and FK fields already shown in `pk`/`fk` are excluded).
    - `"salientTyped"` ? like salientNames but each entry is an object with `name`, `type`, and optionally `required` and `valueMap`.
    - `"allTyped"` ? like salientTyped but includes all fields, not just salient ones.
    - `"full"` ? all fields with the full `salientFieldAttributes` attribute mask.

    Settings:

    - `detail` (String) ? one of the levels above; default `"compact"`.
    - `maxFields` (Integer) ? cap on the number of fields in `otherFields`.
    - `excludeHousekeeping` (Boolean) ? omit auto-populated fields (creator, modifier, creatorTimestamp, modifierTimestamp); default `true` for all modes except `"full"`.
    - `includeData` (String) ? if set, includes representative data samples from available client-side caches. Values: `"fieldValues"` (per-field unique sample values added as `sampleValues` on each field entry) or `"records"` (whole sample records added as `sampleRecords`). Data is sourced from clientOnly cacheData, cacheAllData cacheResultSet, or any default-fetch (no operationId) ResultSet observing the DataSource ? no server requests are triggered.
    - `dataSampleCount` (Integer) ? maximum unique sample values per field (fieldValues mode) or sample records (records mode); default 3.
    - `dataSampleMaxSearch` (Integer) ? maximum cache records to scan when collecting unique sample values; default 100.
    Parameters:
      `dataSource` - DataSource or ID
      `settings` - detail level and field options
    Returns:
      structured summary
    See Also:
      - `getDataSourceSummaries()`

  - ### getEngine

    public static AIEngine getEngine()
    Returns the `AIEngine` having the given engine ID.
    Returns:
      the `AIEngine`, or `null` if the `AIEngine` could not be found.

  - ### getEngine

    public static AIEngine getEngine(String engineId)
    Returns the `AIEngine` having the given engine ID.
    Parameters:
      `engineId` - the engineId of the `AIEngine` to get. If not specified, `defaultEngineId` is used.
    Returns:
      the `AIEngine`, or `null` if the `AIEngine` could not be found.

  - ### getMockingPolicy

    public static String getMockingPolicy()
    Returns the current `mockingPolicy`. The return value is always one of `"none"`, `"auto"`, or `"interactive"`; the legacy `responseSpoofingMode` values `"hybrid"` and `"full"` are normalized before returning.
    Returns:
      The current mocking policy: "none", "auto", or "interactive"

  - ### isEnabled

    public static boolean isEnabled()
    Determines whether AI support is enabled. `disabled` must be set to `false` and the default `AIEngine` must be registered in order to enable the use of AI.
    Returns:
      `true` if the use of AI is enabled; `false` otherwise.
    See Also:
      - `com.smartgwt.client.ai.AI#disabled`
      - `com.smartgwt.client.ai.AI#defaultEngineId`

  - ### pauseDataQuestion

    public static void pauseDataQuestion(String questionId)
    Pauses a data question if not already paused or canceled.
    Parameters:
      `questionId` - The ID of the data question to pause.

  - ### registerEngine

    public static boolean registerEngine(AIEngine engine)
    Registers the given `AIEngine`.
    Parameters:
      `engine` - The `AIEngine` to register.
    Returns:
      `true` if the `AIEngine` was successfully registered; `false` otherwise.
    See Also:
      - `unregisterEngine(java.lang.String)`

  - ### resumeDataQuestion

    public static void resumeDataQuestion(String questionId)
    Resumes a data question if paused.
    Parameters:
      `questionId` - The ID of the data question to resume.

  - ### sendPrompt

    public static void sendPrompt(String dynamicString, Map context, AIResponseCallback callback)
    Evaluates the given `dynamic string` to form a prompt string that is then sent as the request to the default AI engine.

    Within `dynamicString`, any evaluated JavaScript expressions have access to all of the values in the `context` ValueMap.

    Parameters:
      `dynamicString` - A dynamic string. See `DynamicString`
      `context` - A map from each in-scope `Identifier` to its value.
      `callback` - The callback to fire with the response from AI.

  - ### setMockingPolicy

    public static void setMockingPolicy(String policy)
    Sets `mockingPolicy`. Pass one of `"none"`, `"auto"`, or `"interactive"`.
    Parameters:
      `policy` - The mocking policy: "none", "auto", or "interactive"

  - ### unregisterEngine

    public static boolean unregisterEngine(String engineId)
    Unregisters an `AIEngine` specified by its ID.
    Parameters:
      `engineId` - the ID of the `AIEngine` to unregister.
    Returns:
      `true` if the `AIEngine` was successfully unregistered; `false` otherwise.
    See Also:
      - `registerEngine(com.smartgwt.client.ai.AIEngine)`

  - ### moduleLoaded

    public static boolean moduleLoaded()
    Reports whether the optional AI module is loaded for the page.
    Returns:
      true if and only if the AI module has been loaded

  - ### checkModuleLoaded

    public static void checkModuleLoaded(String faultingAction)